Library Reference
Software Development Tolo
Table of Contents
GRAPHICS FUNCTIONS o i a sis e E ees sande aans cos Sena a Sas ote nea sha coun Bad devas E 7
SOUND'RUNC TIONS hae eae ai a eee NEATE EET EER SEEE NEKET EKEN ie 155
STANDARD:C FUNC TIONS: ren i R R E RO A GORTEA 200
MATHEMATICAL FUNCTIONS neonin n a i aa a daas 255
OTHER FUNC TIONS oii eE AE E E A E R AE SE TURR E 286
About NetYaroze
What You Need to Know
In order to get started with Net Yaroze, you should have experience of C programming to a competent level
and a knowledge of a 2D graphic creation/editing tool. In addition, at least a basic grasp of a 3D modelling
packageand a sound creation/editing toolwould be help you get the best out of you NetYaroze kit.
The NetYaroze Manual Set
There are three books in the set of Net Yaroze manuals.
1. Start Up Guide
An introductory booklet explaining the contents and requirements of the NefYaroze Starter Kit. It
also gives step by step instructions on setting up they NetYaroze software on your PC and how to
run Net Yaroze software on the system.
2. User Guide
A reference manual providing details on making software for the NefYaroze system.
3. Library Reference(this document)
A manual listing and describing the functions and structures in the NetYaroze libraries.
Additional Reading
Please see the Additional Reading list at the end of theStart Up Guide
Graphics Functions
RECT
Structure
Members
Comments
Frame buffer rectangular area
typedef struct {
short x, y;
short w, h;
} RECT;
x, y Coordinates for the top left-hand corner of the rectangular area
w, h Width and height of the rectangular area
RECT specifies the area of the frame buffer to be accessed. Negative values or values that
exceed the size of the frame buffer (1024x512) cannot be used.
DRAWENV
Drawing environment
Structure
typedef struct {
RECT clip;
short ofs[2];
RECT tw;
unsigned short tpage;
unsigned char dtd;
unsigned char dfe;
unsigned char isbg;
unsigned char r0, g0, bO;
DR_ENV dr_env,
} DRAWENV,;
Members
clip Drawing area. Drawing is limited to the rectangular area specified by
clip. Drawing cannot be performed outside the clip area
ofs Offset. The values (ofs[0], ofs[1]) are added to all coordinate values to
give the address values used by all drawing commands when drawing
in the frame buffer
tw Texture window. Repeated use is made of the texture pattern
contained in the rectangular area within the texture page
defined by tw
tpage Texture page initial value
dtd Dither treatment flag
0: OFF
1: ON
dfe Flag for drawing to the dsplay area
0: Drawing to the display area is blocked
1: Drawing to the display area is allowed
isbg Clear drawing area flag
0: OFF
1: ON
0: The drawing area is not cleared when the drawing
environment is set up
1: The entire clipped area is painted with the brightness
values (r0,g0,b0) when the drawing environment is set
up.
r0,g0,b0 Background colour. Only available whenisbg = 1.
dr_env Reserved for this system
Comments
DRAWENY sets the basic parameters relating to drawing offset, drawing clip area, etc.
Notes
Within the drawing space, drawing can actually be carried out in the region (0, 0)-(1023,
511).
Offset values and address values to which the offset has been added are wrapped around
using (-1024, -1024)-(1023, 1023).
Values that can be specified for the texture window are limited to the combinations shown
in the following table.
tw.x al multiple of 16 | multiple of 32 | multiple of 64 | multiple of 128
tw.y | oo | multiple of 16 | multiple of 32} multiple of 64 | multiple of 128
DISPENV
Display environment
Structure
typedef struct {
RECT disp;
RECT screen,
unsigned char isinter;
unsigned char isrgb24;
unsigned char pad0, padl;
} DISPENV;
Members
disp Display area within the frame buffer
The width of the area can be set to 256, 320, 360, 512 or 640
The height of the area can be set to 240 or 480
screen Display area on the output screen
The screen area is calculated on the basis of a standard monitor screen
in which the coordinates are (0, 0) for the top left corner and (256,
240) for the bottom right corner, regardless of thedisp value
isinter Interlaced mode flag
0: Non-interlaced
1: Interlaced
isrgb24 24bit mode flag
0: 16bit mode
1: 24 bit mode
Comments
DISPENV specifies parameters for screen display mode, frame buffer display position,
etc.
VECTOR
32bit 3D vectors
Structure
typedef struct {
long vx, vy;
long vz, pad;
} VECTOR;
Members
VX, VY, VZ Vector components
pad Padding
Comments
VECTOR defines the structure of 32 bit 3D vectors.
SVECTOR
Structure
Members
Comments
typedef struct {
} SVECTOR;
VX, VY, VZ
pad
SVECTOR defines the structure of 16bit 3D vectors.
short vx, vy;
short vz, pad;
Vector components
Padding
16 bit 3D vectors
CVECTOR
8bit 3D vectors (colour vectors)
Structure
typedef struct {
unsigned char r, g, b, cd;
} CVECTOR;
Members
r, g, b Vector components
cd Padding
Comments
CVECTOR defines the structure of 8 bit colour vectors.
MATRIX
3 x 3 matrices
Structure
typedef struct {
short m[3][3];
long t[3];
} MATRIX;
Members
m 3x3 matrix coefficient values
t Amount of translation
Comments
Each component is specified using the m{][j] part of MATRIX.
The amount of translation after conversion is specified using the t{] part of MATRIX.
GsOT
Ordering table headers
Structure
struct GsOT {
unsigned short length;
GsOT_TAG “rg;
unsigned short offset;
unsigned short point;
GsOT_TAG “*tag;
};
Members
length OT bit length
org Top address of the GSOT_TAG table
offset OT offset on the Z axis in the screencoordinate system
point OT representative value on the Z axis in the screen
coordinate system
tag Pointer to the current top GSOT_TAG
Comments
GsOT indicates the ordering table header.
This header holds the pointers, org and tag that point to the actual ordering table. org and
tag are both initialised using the GsClearOt() function.
tag points to the top of the ordering table.
Notes
See also
The GsDrawOt() function draws the ordering table to whichtag points.
The value of tag changes because the top is changed using the GsSortClear() or
GsSortOt() functions. org is therefore provided to continue to hold the top of the ordering
table.
The size of the ordering table is set by length. length can be set to any value between 1
and 14. When length is set to 1, org points to a 0~1 GsOT_TAG array, and when length is
set to 14, org points to a 0~16384 GsOT_TAG array.
The GsClearOt() function initialises an area of memory from org up to the size specified
by length. Accordingly, it is important to be aware that if the size of the GGOT_TAG array
pointed to by org is less than the size indicated by length, memory may be damaged.
point refers to the representative value of the ordering table when ordering tables are
sorted among themselves by means of theGsSortOt() function.
offset sets the ordering table offset on the Z axis. For example, if offset = 256 the top of
the ordering table will be at Z = 256. (*1)
The values of length and org must be set at the initialisation stage. The other members are
set using the GsClearOt() function.
*1 Not supported at present.
GsClearOt(),GsDrawOt(),GsSortOt(),GsCutOt()
GsOT_TAG
Ordering table units
Structure
struct GSOT_TAG {
unsigned p : 24;
unsigned char num: 8;
}s
Members
p OT ring pointer
num Word number packet
Comments
The ordering table array will be the array of thisGsOT_TAG.
The ordering table is the “list structure” that points to successive addresses. In the case of
the 32bit address, the lower order 24bit can be displayed byp.
The GsOT_TAG array of the size set by theGsOT member length is secured when the
ordering table is placed in memory.
GsDOBJ2
For GSCOORDINATE2 3D object handler
Structure
struct GSDOBJ2 {
unsigned long attribute;
GsCOORDINATE2 ‘toord2;
unsigned long *tmd;
unsigned long id;
};
Members
attribute Object attribute ( 32bit )
coord2 Pointer to local coordinate system
tmd Pointer to modelling data
id Reserved for the system
Comments
3D models can be manipulated via the structure GSDOBJ2, which is used as the handler
for each 3D model. GsLinkObject4() is used to link GSDOBJ2 to the modelling data of the
TMD file.
Access to linked TMD data is possible via GIDOBJ2. GsSortObject4() is used to register
GsDOB)J2 in the ordering table.
coord2 is the pointer to the coordinate system inherent in the object.
The position, gradient and size of the object are reflected in the coordinate system pointed
by coord2 by setting the matrix.
tmd holds the top address of the modelling data stored in memory in TMD format. tmd is
calculated and set by GsLinkObject4().
attribute is 32bit, and various attributes are set here for the purpose of display.
Comments on each bit are as follows.
(a) Light source calculation ON/OFF switch (bit 6)
This bit is used when the light source calculation is removed.
Texture-mapped polygons are displayed in original texture colour when the light
source calculation is removed. Unmapped polygons are displayed in modelling data
colour as they are.
(b) Automatic division function switch (bit 9-11)
0:
1:
2
3:
4
5
No automatic division
2x2 division
4x4 division
8x8 division
16x16 division
32x32 division
This bit specifies the division number of automatic division. Automatic division is the
function for automatically dividing one polygon at the time of execution. It is used for
decreasing texture distortion and preventing deficiency in neighbouring polygons.
However, division should be kept to a minimum in order to increase the number of
polygons in exponential function terms.
(c) Semi-transparency ON/OFF (bit30)
This puts semi-transparency ON/OFF.
The highest order bit (STP bit) of the texture colour field (texture pattern when direct
is set, CLUT colour field when indexed is set) must be used together with this bit in
order to set semi-transparency. Pixel unitsemi-transparency/opacity can also be
controlled by using this STP bit.
(d) Display ON/OFF (bit31)
This puts display ON/OFF.
GsCOORDINATE2
Matrix type coordinate system
Structure
struct GCCOORDINATE2 {
unsigned long flg;
MATRIX coord;
MATRIX workm
GsCOORD2PARM ‘aram
GsCOORDINATE2 ‘%uper;
};
Members
flg Flag as to whether or notcoord has been rewritten
coord Matrix
workm The result from this coordinate system to the WORLDcoordinate
system
param Pointer for using scale, rotation and transfer parameters
super Pointer to the parent coordinates
Comments
GsCOORDINATE2 holds parent coordinates and is defined according to the MATRIX
type coord.
When the matrix is multiplied by the GsGetLw() or GSGETLs() function in each node of
GsCOORDINATE2 from the WORLBoordinates, its result is held in workm
However, it does not store the result in workm of the coordinate system that is directly
connected to the WORLDcoordinate system.
At the time of GsGetLw() and GsGetLs() calculation, flg is referred to in order to avoid
calculation of nodes that have already been calculated. 1 is to set, 0 is to clear.
The programmer must take responsibility for clearing this flag if the content of coord is
changed. Otherwise, the GsGetLw()and GsGetLs() functions will be defective.
GsVIEW2
Structure
struct GSVIEW2 {
}
Members
view
super
Comments
Viewpoint position (MATRIX type)
MATRIX view,
GsCOORDINATE2 ‘Super
Matrix for conversion from parentcoordinates to viewpoint
coordinates
Pointer to the coordinate system that sets the viewpoint
GSVIEW2 sets the viewpointcoordinate system. It directly specifies the matrix for
converting from the parentcoordinate system to the viewpointcoordinate system in view.
The setting function is GsSetView2().
GsRVIEW2
Viewpoint position (REFERENCE type)
Structure
struct GSRVIEW2 {
long vpx, vpy, vpz
long vpx, vpy, vpz;
long rz;
GsCOORDINATE2 ‘Super
bs
Members
VpX, Vpy; VpZ Viewpoint coordinates
Wx, Wry, WIZ Reference point coordinates
rz Viewpoint twist
super Pointer to the coordinate system that sets the viewpoint
(GsCOORDINATE2 type)
Comments
GsVIEW2 holds the viewpoint information, and is set according to the GsSetRefView2()
function.
The coordinates of the viewpoint in the coordinate system displayed by super are set in
(VPX, vpy, VpZ).
The coordinates of the reference point in the coordinate system displayed by super are set
in (wrx, vry, vrz).
rz is specified in fixed decimal point format with the gradient for the screen z axis when
the z axis is the vector from the viewpoint to the reference point, set so that 4096 is one
degree.
The coordinate systems of the viewpoint and reference point are set in super. For
example, a cockpit view can be easily created with this function by setting super in the
coordinate system of an aeroplane.
GsF_LIGHT
Parallel light source
Structure
struct GSF_LIGHT {
long vx, vy, VZ;
unsigned char r, g, b;
J:
Members
VX, VY, VZ Light source direction vectors
r, g, b Light colours
Comments
GsF_LIGHT holds parallel light source information and is set in the system by the
GsSetFlatLight() function.
Up to three parallel light sources can be set at the same time.
Sets the direction vectors of the light source in (vx, vy, vz). The programmer does not have
to carry out standardisation as this is done by theGsSetFlatLight function.
The light shines strongest on normal vector polygons whose directions are opposite to
these vectors.
Sets the colours of the light source in ¢,g,b) by 8bit.
GsFOGPARAM
Fog (depth queue) information
Structure
struct GFFOGPARAM {
short dqa;
long dqb;
unsigned char rfc, gfc, bfc;
j;
Members
dqa Parameter of the degree of merging in relation to depth
dqb Parameter of the degree of merging in relation to depth
rfc, gfc, bfc Background colours
Comments
dqa and dqb are the attenuation coefficients to the background colour.
dqa and dqb can be shown according to the following formula.
dqa = -df * 4096/64/h
dqb = 1.25 * 4096 * 4096
df is where the attenuation coefficients become one. In other words it is the distance from
the viewpoint to the point where the background colour completely merges into the distant
view.
h is the distance from the viewpoint to the screen. In other words it indicates the
projection distance.
GsIMAGE
Image data configuration information
Structure
struct GIIMAGE {
short pmode
short px, py;
unsigned short pw, ph;
unsigned long *pixel;
short cx, cy;
unsigned short cw, ch;
unsigned long *clut;
Members
pmode Pixel mode
0: Abit CLUT
1: 8bit CLUT
2: 16bit DIRECT
3: 24bit DIRECT
4: Other mode mixtures
PX py Pixel data storage positions
pixel Pointer to pixel data
Cx, cy CLUT data storage positions
Comments
cw, ch CLUT data width/ height
clut Pointer to CLUT data
GsImage is the structure for storing TIM format data information using the
GsGetTimInfo() function.
For file format, please refer to the NetYaroze Members' Web site.
GsSPRITE
Structure
Members
struct GSSPRITE {
attribute
X, y
w, h
tpage
u, V
CX, Cy
unsigned long attribute;
short x, y;
unsigned short w, h;
unsigned short tpage;
unsigned char u, v;
short cx, cy;
unsigned char r, g, b;
short mx, my;
short scalex, scaley,
long rotate;
Sprite handler
32bit length attribute (details are given below)
Top left-hand point display positions
Sprite width and height (not displayed when either w or h is 0)
Sprite pattern texture page number
Sprite pattern in-page offset
Sprite CLUT address
r, g, b
mx, my
scalex, scaley
rotate
attribute bits
Brightness is set for each of r, g and b when they
are displayed (Original brightness when it is 128)
Rotation/ expansion central coordinates
x and y direction scaling values
Rotation angle (Units: 4096 = P (degree))
6: Brightness regulation
0: ON
1: OFF
24-25: Sprite pattern bit mode
0: 4bitCLUT
1: 8bitCLUT
2: 15bitDirect
27: Rotation scaling function
0: ON
1: OFF
28-29: Semi-transparency rate
0: 0.5 x Back + 0.5 x Forward
1: 1.0 x Back + 1.0 x Forward
2: 1.0 x Back - 1.0 x Forward
3: 1.0 x Back + 0.25 x Forward
30: Semi-transparency ON /OFF
0: Semi-transparency OFF
1: Semi-transparency ON
31: Displayed/ Not displayed
0: Display
1: No display
Comments
GsSPRITE is the structure that holds information for displaying sprites and prepares one
for each sprite displayed. The sprites can be operated via the parameters.
Either GsSortSprite() or GsSortFastSprite() may be used to register GsSPRITE in the
ordering table.
The on-screen display position is specified as (x, y). The points specified as (mx, my) in
the sprite pattern are the positions specified in the GsSortSprite() function, and the top
left-hand points of the sprites are the positions specified in the GsSortFastSprite()
function.
The width and length of the sprites are specified in pixel units as (w, h).
Texture page numbers, where there are sprite patterns, are specified astpage (0~31).
The top left-hand points of the sprite patterns are specified with in-page offset as 4, v). A
range (0,0)~(255,255) can be specified.
The top positions of CLUT (Colour palette) are specified by the VRAM address asdx,
cy) (only valid at the time of 4bit/8bit).
Brightness is specified for each of r, g and b as (r, g, b). Values from 0~255 can be
specified. The brightness of the original pattern is attained at 128 and double the
brightness at 255.
Rotation expansion central coordinates are given as (mx, my) as relative coordinates
whose origins are the top left-hand points of the sprites. For example, one half of the
width and length is specified if it is rotated at the centre of the sprite.
The scaling values are given for the x and y directions as (scalex, scaley). The unit is
4096 = 1.0 (original size). It can be set up to a maximum of eight times.
rotate sets rotation around the Z axis in fixed decimal point format with 4096 as | degree.
attribute is 32bit in which various attributes are set for display.
Comments on each bit are as follows.
(a) Brightness adjustment ON/OFF switch (bit 6)
This sets whether or not the sprite pattern pixel colours are to be drawn with
brightness adjusted according to the (,g,b) values. When it is 1, brightness is not
adjusted and the (r,g,b) values are disregarded.
(b) Bit mode (bit 24-25)
In the sprite patterns there are 4bit and 8bit modes that use colour tables and a 15bit
mode that displays colour directly. This is specified here.
(c) Rotation scaling function (bit 27)
Switches the sprite expansion function ON/OFF. If it is switched off when sprite
rotation and expansion are not carried out, processing will be speeded up.
This bit is also disregarded in the case of the GsSortFastSprite() function, and the
expansion function is always turned OFF.
(d) Semi-transparency rate (bit 28-29)
Sets the method of pixel blending whensemi-transparency is turned ON with bit 30.
Normal semi-transparent processing is performed when set to 0, pixel addition when
set to 1, pixel subtraction when set to 2, and 25% addition when set to 3.
(e) Semi-transparency ON/OFF (bit 30)
It turns semi-transparency ON/OFF.
The highest order bit (STP bit) of the texture colour field (texture pattern when direct
is set, CLUT colour field when indexed is set) must be used together with this bit in
order to set semi-transparency.
Pixel unit semi-transparency/opacity can also be controlled by using this STP bit.
(f) Display ON/OFF (bit 31)
Turns display ON/OFF.
GsBG
Structure
Members
struct GsBG {
attribute
x, y
w, h
scrollx, scrolly
r, g, b
map
BG (background picture) handler
unsigned long attribute;
short x, y;
short w, h;
short scrollx, scrolly;
unsigned char r, g, b;
GsMAP *map;
short mx, my;
short scalex, scaley,
long rotate;
Attribute
Display positions of the top left-hand points
BG display size (pixel unit)
x,y scroll value
Brightness is set for each of r, g and b when they are
displayed (Original brightness when 128)
Pointer to map data
Comments
mx, my Rotation/ expansion central coordinates
scalex, scaley x and y direction scaling values
rotate Rotation angle (Units: 4096 = P (degree))
BG (Background) is a function for drawing one large rectangle constructed by thGsMAP
data combining small rectangles defined byGsCELL data.
BG can be operated via the structure of thisGsBG, which exists in each BG.
The on-screen display position is specified as «, y).
The display size of BG is specified as (w, h). Units are pixels and do not depend on the
cell size or the size of map.
The content of the map is also displayed repeatedly if the display area is larger than the
size of the map. (Tiling function)
(scrollx, scrolly) are the display position offsets in the map and are specified in dot units.
Brightness is specified for each of r, g and b as (r, g, b). It becomes the original colour at
128 and double the brightness at 255.
map is the pointer to the GSMAP format map data to which the top address of the map
data is specified.
Rotation expansion central coordinates are given as (mx, my) as relative coordinates
whose origins are the top left-hand points of BG. For example, one half of the width and
length is specified if it is rotated at the centre BG.
The scaling values are given for the x and y directions as (scalex, scaley). The unit is
4096 = 1.0 (original size). It can be set up to a maximum of eight times.
The rotation angle around the z axis is specified asrotate (4096 = 1 degree).
Please refer to GsSprite regarding attribute.
GsMAP
Structure
Members
Comments
struct GsMAP {
cellw, cellh
ncellw, ncellh
base
index
BG composition MAP
unsigned char cellw, cellh;
unsigned short ncellw, ncellh;
GsCELL *base;
unsigned short *index,
Cell size (taken as 256 in the case of 0)
Size of BG (unit is cell)
Pointer to the GSCELL structure array
Pointer to the cell array information
GsMAP is map data (cell array information) for composing BG witIGsCELL. The map
data controls the information by cell index array.
The size of one cell is specified in pixel units as €ellw, cellh). Note also that one BG is
formed from a cell of the same size.
The size of map held by BG is specified in cell units as(ncellw, ncellh).
The top address of the GsCell array is set as base.
The top address of the cell array information table is set as index. The cell array
information indicates the index value for the above array shown in base as ncellw x
ncellh A NULL cell (transparent cell) is indicated if the index value is Oxffff.
GsCELL
BG configuration cell
Structure
struct GSCELL {
unsigned char u, v;
unsigned short cba;
unsigned short flag;
unsigned short tpage;
bs
Members
u Offset from within the page (X direction)
v Offset from within the page (Y direction)
cba CLUT ID
flag Inversion information
tpage Texture page number
Comments
GsCELL is the structure holding information about the cell that composes BG and it is
secured in the memory as an array.
The position of the sprite pattern corresponding to its cell is specified as ú, v) by offset in
the page specified as tpa ge.
cba is the data that displays the position within the frame buffer of the CLUT
corresponding to its cell, as follows.
X position of CLUT/16
bit6~15 Y position of CLUT
flag holds information as to whether or not that cell displays the original texture pattern
inversely.
bit Vertical inversion (no inversion when set to 0, inversioj
when set to 1)
bitl Horizontal inversion (no inversion when set to 0,
inversion when set to 1)
tpage is the page number displaying the position within the frame buffer of the sprite
pattern.
GsLINE
Structure
Members
struct GsLINE {
attribute
Straight line handler
unsigned long attribute;
short x0, y0;
short x1, yl;
unsigned char r, g, b;
Attribute
28-29: Semi-transparency rate
30: Semi-transparency ON OFF
0:
1:
31: Display ON OFF
0:
1:
2:
3:
0.5 x Back + 0.5 x Forward
1.0 x Back + 1.0 x Forward
1.0 x Back - 1.0 x Forward
1.0 x Back + 0.25 x Forward
Semi-transparency OFF
Semi-transparency ON
Display
No display
Comments
x0, y0 Position of drawing start point
xl, yl Position of drawing end point
r, g, b Drawing colour
GsLINE is the structure that holds information necessary for drawing straight lines. The
GsSortLine() function is used to registerGsLINE in the ordering table.
attribute is 32bit, and various attributes are set here for the purpose of display.
(a) Semi-transparency rate (bit28-29)
GsLINEsets the pixel blending method when semi-transparency is turned ON by
bit30. Normal semi-transparency processing is performed when set to 0, pixel addition
when set to 1, pixel subtraction when set to 2, and 25% addition when set to 3.
(b) Semi-transparency ON/OFF (bit30)
Turns semi-transparency ON/OFF
(c) Display ON/OFF (bit3 1)
Turns display ON/OFF
GsGLINE
Gradation straight line handler
Structure
struct GSGLINE {
unsigned long attribute;
short x0, y0;
short x1, yl;
unsigned char r0, g0, bO;
unsigned char rl, gl, bl;
};
Members
attribute Attribute
28-29: Semi-transparency rate
0: 0.5 x Back + 0.5 x Forward
1: .0 x Back + 1.0 x Forward
2: 1.0 x Back - 1.0 x Forward
3: 1.0 x Back + 0.25 x Forward
30: Semi-transparency ON OFF
0: Semi-transparency OFF
1: Semi-transparency ON
31: Display ON OFF
0: Display
1: No display
Comments
x0, yO
xl, yl
r0, g0, bO
rl, gl, bl
Position of drawing start point
Position of drawing end point
Start point drawing colour
End point drawing colour
GsGLINE is the structure that holds information necessary for drawing gradation straight
lines. It is the same as for GsLINE except that drawing colour specification can be
separately set at the start point and end point.
GsBOXF
Rectangle handler
Structure
struct GSBOXF {
unsigned long attribute;
short x, y;
unsigned short w, h;
unsigned char r, g, b;
};
Members
attribute Attribute
28-29: Semi-transparency rate
0: 0.5 x Back + 0.5 x Forward
1: 1.0 x Back + 1.0 x Forward
2: 1.0 x Back - 1.0 x Forward
3: 1.0 x Back + 0.25 x Forward
30: Semi-transparency ON OFF
0: Semi-transparency OFF
1: Semi-transparency ON
31: Display ON OFF
0: Display
1: No display
Comments
x, y Display position (top left-hand point)
x,y Size of rectangle (width, height)
r, g, b Drawing colour
GsBOXF is the structure that holds information necessary for rectangles painted by single
colours. The GsSortBoxFill() function is used to registerGsBOXF in the ordering table.
ResetGraph
Format
int ResetGraph (
int mode
)
Arguments
mode
Comments
Initialises graphics system
Set mode
0:
All reset. The drawing environment and display
environment are initialised.
The current drawing is cancelled and the command queue
is flushed.
It resets the graphics system with the mode that is specified bymode.
Return Value
None
SetDispMask
Sets display mask
Format
void SetDispMask(
int mask
)
Arguments
mask 0: Display is not carried out in ‘Display’.
1: Display is carried out in ‘Display’.
Comments
It allows display to ‘Display’
Return Value
None
PutDrawEnv
Sets drawing environment
Format
DRAWENV *PutDrawEnv(
DRAWENV “env
)
Arguments
env Drawing environment
Comments
Sets the basic parameters relating to drawing, e.g. drawing offset and drawing clip area.
Return Value
Top address of env
Notes
The drawing environment specified byPutDrawEnv() is valid until PutDrawEnv() is
executed or GsSwapDispBuff() is called.
See Also
GsSwapDispBuff), DRAWENV
PutDispEnv
Sets display environment
Format
DISPENV *PutDispEnv(
DISPENV “env
)
Arguments
env Display environment
Comments
PutDispEnv sets the display environment. The display environment is immediately
executed at the point in time when the function is called.
Return Value
Top address of env
Notes
The drawing environment specified byPutDispEnv() is valid until PutDispEnv() is
executed or GsSwapDispBuff() is called.
See Also
GsSwapDispBuff(), DISPENV
LoadImage
Format
Arguments
Comments
Return Value
Notes
Transmits data to frame buffer
int LoadImage(
RECT *recp,
u_long *p
recp Transmission destination rectangular area
p Transmission source main memory address
LoadImage transmits data below the addressp to the rectangular area of the frame buffer
specified by recp.
Queue number
Actual completion of the transmission needs to be identified byDrawSync() because it is a
non-blocking function.
The transmission area is not affected by the drawing environment (clip and offset).
The transmission area needs to fit into the area in which drawing is possible (0,0) -
(1023,511).
Storelmage
Transmits data from frame buffer
Format
int Storelmage (
RECT *recp,
u_long *p
)
Arguments
recp Transmission source rectangular area
p Transmission destination main memory address
Comments
StoreImage transmits the rectangular area of the frame buffer specified byecp to below
the address p.
Return Value
Queue number
Notes
Actual completion of the transmission needs to be identified byDrawSync() because it is a
non-blocking function.
The transmission area is not affected by the drawing environment (clip and offset).
The transmission area needs to fit into the area in which drawing is possible (0,0) -
(1023,511).
Movelmage
Format
Arguments
Comments
Return Value
Notes
Transmits data between frame buffer
int Movelmage(
RECT *recp,
int x,
int y
)
recp Transmission source rectangular area
x,y Transmission destination rectangular area top left-hand point
Movelmage transmits the rectangular area of the frame buffer specified byecp to a
rectangular area of the same size starting fromx,y.
Queue number
Actual completion of the transmission needs to be identified byDrawSync() because it is a
non-blocking function.
The transmission area is not affected by the drawing environment (clip and offset).
The transmission area needs to fit into the area in which drawing is possible (0,0) -
(1023,511) for both the transmission source and transmission destination.
The content of the transmission source is stored. Also, the function cannot be guaranteed
if the areas of transmission source and transmission destination are overlapping,
ClearImage
Format
Arguments
Comments
Return Value
Notes
Frame buffer high speed painting
int ClearImage (
RECT “*recp,
u_char r,
u_char g,
u_char b
)
recp Painting rectangular area
r, g, b Painting pixel value
ClearImage paints the rectangular area of the frame buffer specified byrecp with the
(r,g,b) brightness value.
Queue number
Actual completion of the transmission needs to be identified byDrawSync() because it is a
non-blocking function.
The transmission area is not affected by the drawing environment (clip and offset).
GetTPage
Calculates primitive tpage member value
Format
u_short GetTPage (
int tp,
int abr,
int x,
int y
)
Arguments
tp Texture mode
0: 4bitCLUT
1: 8bitCLUT
2: 16bitDirect
abr Semi-transparency rate
0: 0.5 x Back + 0.5 x Forward
1: 1.0 x Back + 1.0 x Forward
2: 1.0 x Back - 1.0 x Forward
3: 1.0 x Back + 0.25 x Forward
x,y Texture page address
Comments
GetTPage calculates the texture page ID and returns it.
Return Value
Texture page ID
Notes
The semi-transparency rate is also valid for polygons that do not carry out texture
mapping.
The texture page address is limited to multiples of 64 in the x direction and multiples of
256 in the y direction.
GetClut
Calculates primitive clut member value
Format
u_short GetClut (
int x,
int y
)
Arguments
x, y CLUT frame buffer address
Comments
GetClut calculates the texture CLUT ID and returns it.
Return Value
CLUT ID
Notes
The CLUT address is limited to multiples of 16 in the x direction.
DrawSync
Format
Arguments
Comments
Return Value
Waits for completion of all drawing
int DrawSync(
int mode
)
mode 0: Waits for completion of all non-block functions registered in
the queue.
1: The current rank number of the queue is checked and
returned.
DrawSync waits for completion of the drawing.
Actual queue rank number
VSync
Waits for vertical synchronisation
Format
int VSyndq
int mode
)
Arguments
mode 0: Blocking until vertical synchronisation occurs.
1: The time elapsed from the point in time when VSync() was previously
called is returned in units of one horizontal synchronisation interval.
n: (n>1) Counting from the point in time whenVSync() was previously
called and blocking up to n times the occurrence of vertical
synchronisation.
n: (n<0) Absolute time from program activation is returned in vertical
synchronisation interval units.
Comments
Vsync waits for vertical synchronisation.
Return Value
mode=0 Time elapsed from point in time when VSync() was previously
called (horizontal return unit)
mode<0 Time elapsed from program activation (vertical return unit)
VSyncCallback
Sets vertical synchronisation callback function
Format
int VSyncCallback
void (*func)()
)
Arguments
func Callback function
Comments
the function func is called when vertical return section commence.
Callback does not occur when 0 is specified infunc.
Return Value
None
Notes
Subsequent drawing completion interruptions are masked withinfunc. Therefore, func
needs to return as soon as possible after completion of the necessary processing.
FntLoad
Transmits font pattern
Format
void FntLoad(
int tx,
int ty
)
Arguments
tx, ty Top left coordinate of the area of frame buffer that arranges the
font patterns
Comments
FntLoad transmits to the frame buffer the font pattern used for debugging.
Return Value
None
Comments
FntLoad loads the basic font pattern (4bit texture 256x128) to the frame buffer, and
initialises all print streams.
Notes
FntLoad() must without fail be executed beforeFntOpen() and FntFlush().
The font area must not conflict with the frame buffer area used by the application.
FntOpen
Format
Arguments
Comments
int FntOpen(
int x,
int y,
int w,
int h,
int isbg,
intn
)
X, y
w, h
isbg
Opens print stream
Display start positions
Display area
Background automatic clearance
0: Background is cleared to (0,0,0) when displayed.
1: Background is not cleared to (0,0,0) when displayed.
Number of letters
FntOpen opens the stream used for printing on screen. Thereafter, the largest n character
string of letters can be printed in the rectangular area of the frame buffer &,y)-(x+w, y+h)
using the FntPrint() function.
If 1 is specified inisbg, the background is cleared when a character string is drawn.
Return Value
Print stream ID
Notes
Up to 8 streams can be opened at the same time.
Opened streams cannot be closed until the next FntLoad() is called.
FntPrint
Output to print stream
Format
int FntPrint(
int id,
format,
)
Arguments
id Print stream ID
format Print format
Comments
FntPrint sends the character string to the print stream by theprintf() interface.
Return Value
Character string within the stream
Notes
The actual display of the character string occurs whenFntFlush() is executed.
FntFlush
Draws print stream contents
Format
u_long *FntFlush(
int id
)
Arguments
id Print Stream ID
Comments
FntFlush draws the print stream in the frame buffer.
Return Value
Temporary OT top pointer used in drawing
Notes
After completion of drawing, the print stream contents are also flushed.
KanjiFntOpen
Opens print stream
Format
int KanjiFntOpen(
int x,
int y,
int w,
int h,
int dx,
int dy,
int cx,
int cy,
int isbg,
intn
)
Arguments
x, y Display start positions
w, h Display area
dx,dy Kanji font pattern frame buffer address
CX,cy Kanji clut frame buffer address
isbg Background automatic clearance
0: Background is cleared to (0,0,0) when displayed.
1: Background is not cleared to (0,0,0) when displayed.
n Number of letters
Comments
Return Value
Notes
KanjiFntOpen opens the stream used for printing on screen. Thereafter, the largest n
character string can be printed in the rectangular area of the frame buffer(x,y)-(x+ w, y+h)
using the KanjiFntPrint() function.
If 1 is specified inisbg, the background is cleared when a character string is drawn.
Print stream ID
Up to 8 streams can be opened at the same time.
Opened streams cannot be closed until the next KanjiFntLoad() is called.
The Kanji font area must not conflict with the frame buffer area used by the application.
KanjiFntClose
Closes print stream
Format
int KanjiFntClosd void )
Arguments
None
Comments
This function closes all the streams currently openans are used by KanjiFntPrint() and
initialize the state.
Return Value
None
Notes
Since KanjiFntClose() only initializes the internal state, this function operations even
when there is no stream.
KanjiFntPrint
Format
Arguments
Comments
Return Value
Notes
Outputs to print stream
int KanjiFntPrint(
int id,
format,
)
id Print stream ID
format Print format
KanjiFntPrint sends the SHIFT-JIS full-width character string to the print stream by the
printf() interface.
Character string within the stream
The Kanji code must be SHIFT-JIS.
Full-width and half-width characters can be mixed in the character string, but they are all
changed to full-width at the time of display. Half-width kana are not supported. The actual
display of the character string occurs whenKanjiFntFlush() is executed.
KanjiFntFlush
Draws print stream contents
Format
u_long *KanjiFntFlush (
int id
)
Arguments
id Print Stream ID
Comments
FntFlush draws the print stream contents in the frame buffer.
Return Value
Temporary OT top pointer used in drawing
Notes
After completion of drawing, the print stream contents are also flushed.
Krom2Tim
Format
Arguments
Comments
Converts SHIFT-JIS character strings to 4 bit CLUT data
int Krom2Tim(
u_char *sjis,
u_long *taddr,
int dx,
int dy,
int cx,
int cy,
u_int fg,
u_int bg
)
sjis
taddr
dx, dy
CX, cy
fg, bg
SHIFT-JIS Character String
Data storage area
px,y coordinates on pixel data VRAM
x,y coordinates on clut data VRAM
Character colour and bg colour
Krom2Tim converts the SHIFT-JIS character string to 4 bitslut TIM data and returns to
taddr.
Return Value
Notes
-1 is returned if an irregular code is transferred.
The Kanji code must be SHIFT-JIS. Full-width and half-width characters can be mixed in
the character string , but they are all changed to full-width at the time of display. Half-
width kana are not supported.
For the area specified bytaddr, the size shown in the following formula must be secured
in advance.
128 x (character string specified bysjis) + 84(byte)
Krom2Tim2
Format
Arguments
Comments
Converts SHIFT-JIS character strings to 4 bit CLUT Tim data
int Krom2TimX
u_char *sjis,
u_long *taddr,
int dx,
int dy,
int cdx,
int cdy,
u_int fg,
u_int bg
)
sjis SHIFT-JIS Character String
taddr Starting address of the converted TIM data
dx, dy Pixel data x,y coordinates on VRAM
CX, Cy Clut data x,y coordinates on VRAM
fg, bg Front and background colour
Krom2Tim?2 converts the SHIFT-JIS character string to 4 bitelut TIM data and returns
the starting address in taddr. This is user defined character support version of
Krom2Tim.
Return Value
Notes
-1 is returned if an invalid code is transferred.
The Kanji code must be in SHIFT-JIS. Although both ZENKAKU (double byte) and
HANKAKU (single byte) can be mixedwitha string, all of them will not be converted to
ZENKAKU. Please notethant HANKAKU KANA is not supported.
Prior to calling this function, the area specified bytaddr' must be reserved with the size
derived from the equation below.
Num: number of characters specified bysjis.
If (num<16)
(32 * num + 16) * 4 (bytes)
else
(32 * 16* ((num-1/16 + 1) +16) * 4 (bytes)
MulMatrix0
Takes product of two matrices
Format
MATRIX* MulMatrix0(
MATRIX “m0,
MATRIX “ml,
MATRIX “m2
)
Arguments
m0,m1 Input matrix
m2 Output matrix
Comments
MulMatrix0 takes the product of the two matrices m0 and m1. The value is stored inm2.
The argument format is as follows.
m0,m1,m2->m{[iJ[j] : (1,3,12)
Return Value
Notes
The rotation matrix is fragmented
ApplyMatrix
Multiplies vector by matrix
Format
VECTOR* ApplyMatrix(
MATRIX *m,
SVECTOR ‘V0,
VECTOR *1
)
Arguments
m Input multiplication matrix
vO Input short vector
vl Output vector
Comments
ApplyMatrix multiplies from the right the short vectorv0 by the matrix m and stores the
result in the vector v1.
The argument format is as follows.
m->m[i][j] : (1,3,12)
v0->vx,vy,vz :(1,15,0)
vl->vx,vy,vz :(1,31,0)
Return Value
vl
Notes
The rotation matrix is fragmented.
ApplyMatrixSV
Multiplies vector by matrix
Format
SVECTOR* ApplyMatrixSV(
MATRIX *m,
SVECTOR *0,
SVECTOR *v1
)
Arguments
m Input multiplication matrix
vO Input short vector
vl Output short vector
Comments
ApplyMatrixSV multiplies from the right the short vectorv0 by the matrix m and stores
the result in the short vector v1.
The argument format is as follows.
m->m[i][j] : (1,3,12)
v0->vx,vy,vz :(1,15,0)
vl->vx,vy,vz :(1,15,0)
Return Value
vl
Notes
The rotation matrix is fragmented.
ApplyMatrixLV
Multiplies vector by matrix
Format
VECTOR* ApplyMatrixL V(
MATRIX *m,
VECTOR *v0,
VECTOR *1
)
Arguments
m Input multiplication matrix
vO Input vector
vl Output vector
Comments
ApplyMatrixSV multiplies from the right the short vectorv0 by the matrix m and stores
the result in the short vector v1.
The argument format is as follows.
m->mf[i][j] : (1,3,12)
v0->vx,vy,vz :(1,31,0)
vl->vx,vy,vz :(1,31,0)
Return Value
vl
Notes
The rotation matrix is fragmented
RotMatrix
Searches for rotation matrix from rotation angle
Format
MATRIX*RotMatr ix (
MATRIX *m
SVECTOR *
)
Arguments
m Output rotation matrix
r Input rotation angle
Comments
RotMatrix supplies to matrix m the rotation matrix according to the rotation angle ¢-
>vx->vyys->vz). The rotation angle supplies 4096 as 360, and 4096 is given as 1.0 for
the matrix component.
The matrix is an expansion of the following product. Using the GTEcoordinate
conversion function, the vectors are multiplied from the right, thus the matrix rotates
around the Z, Y and X axes in that order.
1 0 0 cl 0 sl c2 -s2 0
0 c0 -sO/*} 0 1 0l|*řís2 c2 0
0 sO c0 -sl 0 cl 0 0 1
Return Value
Angle value
c0=cos(t->vx), sO=sin(r->vx)
cl=cos(t->vy), sl1=sin(->vy)
c2=cos(t->vz), S2=sin(t->vz)
The argument format is as follows.
m->mli][j] : (1,3,12)
r->vx,vy,vz :(1,3,12) (however 360 is 1.0)
RotMatrixX
Format
Arguments
Comments
Searches for rotation matrix around the X Axis
MATRIX*RotMatrixX (
long r,
MATRIX *m
)
r Input rotation angle
m Input and output rotation matrix
RotMatrixX supplies to matrix m the matrix multiplied by the rotation matrix around the
X axis according to the rotation angler. The rotation angle supplies 4096 as 360°, and
4096 is given as 1.0 for the matrix component.
The matrix is as follows.
1 0 0
0 c -s|*m
0 s c
* c=cos(r), s=sin(r)
The argument format is as follows.
m->mli][j] : (1,3,12)
r:(1,3,12) (however 360 is 1.0)
Return Value
RotMatrixY
Format
Arguments
Comments
Searches for rotation matrix around the Y Axis
MATRIX*RotMatrixyY (
long r,
MATRIX *m
)
r Input rotation angle
m Input and output rotation matrix
RotMatrixY supplies to matrix m the matrix multiplied by the rotation matrix around the
Y axis according to the rotation angler. The rotation angle supplies 4096 as 360°, and
4096 is given as 1.0 for the matrix component.
The matrix is as follows.
c 0 -=s
0 1 0 |*m
s 0 c
c=cos(r), s=sin(r)
The argument format is as follows.
m->mf[i][j] : (1,3,12)
r:(1,3,12) (however 360° is 1.0)
Return Value
RotMatrixZ
Format
Arguments
Comments
Searches for rotation matrix around the Z Axis
MATRIX*RotMatrixZ (
long r,
MATRIX *m
)
r Input rotation angle
m Input and output rotation matrix
RotMatrixZ supplies to matrix m the matrix multiplied by the rotation matrix around the
Z axis according to the rotation angler. The rotation angle supplies 4096 as 360°, and
4096 is given as 1.0 for the matrix component.
The matrix is as follows.
* c=cos(r), s=sin(r)
The argument format is as follows.
m->mli][j] : (1,3,12)
r:(1,3,12) (however 360° is 1.0)
Return Value
TransMatrix
Supplies amount of translation
Format
MATRIX* TransMatr ix (
MATRIX“*m,
VECTOR*v
)
Arguments
m Output matrix
v Input shift vector
Comments
TransMatrix supplies to matrix m the amount of translation shown byv.
The argument format is as follows.
m->m{i][j] : (1,3,12)
m->tļ[i]: (1,31,0)
v->vx,vy,vz : (1,31,0)
Return Value
ScaleM atrix
Format
Arguments
Comments
MATRIX* ScaleMattr ix (
MATRIX“*m,
VECTOR*v
)
m Output matrix
Input scale vector
Supplies scaling factor
ScaleMatrix supplies to matrix m the scaling factor shown byv. It is a fixed decimal point
number with 4096 as 1.0 for the v component.
a00 a0l
Ifm=|al0 all
a20 a2l
a00 * sx
then m=] a10 * sx
a20 * sx
a02
al2}.v=[sx sy sz]
a22
a0l*sy a02*sz
all*sy al2*sz
a21*sy a22*sz
The argument format is as follows.
m->mfi][j] : (1,3,12)
v->vx,vy,vz : (1,19,12)
Return Value
ScaleMatrixL
Format
Arguments
Comments
MATRIX* ScaleMatrixL (
MATRIX*m,
VECTOR*v
)
m Output matrix
Input scale vector
Supplies scaling factor
ScaleMatrixL supplies to matrixm the scaling factor shown byv. It is a fixed decimal
point number with 4096 as 1.0 for the v component.
a00 a0l
Ifm=| al0 all
a20 a2l
a00 * sx
then m=| a10 * sx
a20 * sx
a02
al2|.v=[sx sy sz]
a22
a0l*sy a02*sz
all*sy al2*sz
a21*sy a22*sz
The argument format is as follows.
m->mli][j] : (1,3,12)
v->vx,vy,vz : (1,19,12)
Return Value
TransposeMatrix
Format
Arguments
Comments
Return Value
Supplies rotation value matrix
MATRIX* TransposeMatrix(
MATRIX*m0¢ C
MATRIX*ml
)
m0 Input matrix
ml Output matrix
TransposeMatrix supplies to m1 the rotation value matrix of matrixm0.
The argument format is as follows.
m0->mfi][j] : (1,3,12)
ml->m{i][j] : (1,3,12)
ml
Comp Matrix
Format
Arguments
Comments
Carries out coordinate conversion synthesis
MATRIX*Comp Matrix(
MATRIX*m0,
MATRIX*ml,
MATRIX*m2
)
m0 Input matrix
ml Input matrix
m2 Output matrix
CompMatrix carries out synthesis ofcoordinate conversion matrices including translation.
[m2->m] = [m0->m] * [m1->m]
(m2->t) = [m0->m] * (m1->t) + (m0->t)
However the value of them1->t component must be within the range of (2R ls } A
The argument format is as follows.
m0->mf[i][j] : (1,3,12)
]: (1,31,0)
ml->mfi][j] : (1,3,12)
]: (1,15,0)
->m[i][j] : (1,3,12)
m2->t[i]: (1,31,0)
m0->t[i
m1 ->t[i
Return Value
Notes
The rotation matrix is fragmented.
PushMatrix
Evacuates rotation matrix to stack
Format
void PushMatrix( void )
Arguments
None
Comments
PushMatrix evacuates the rotation matrix to the stack. The stack is up to 20 levels.
Return Value
None
PopMatrix
Resets rotation matrix from stack
Format
void Pop Matrix ( void )
Arguments
None
Comments
PopMatrix resets the rotation matrix from the stack.
Return Value
None
eteMIMefunc
Adds differential data array from multiplication of vertex data
array by coefficient
Format
void gteMIMefunc(
SVECTOR “otp,
SVECTOR “dfp,
long n,
long p
)
Arguments
otp Input/output vertex array
dfp Input differential array
n Input vertex (differential) data number
p Input MIMe weight (control) coefficient
Comments
gteMIMefunc is a subroutine which executes interpolation using the differential data array
and the vertex data array used in the multiple interpolation (MIMe) operation.
p is the fixed decimal point data of the decimal 12bit.
This function executes at high speed the same operation as the following program.
void gteMIMefunc(SVECTOR tp, SVECTOR “dfp, long n, long p)
{
int i;
for(i = 0; i< n; i++){
(otpti)->x += ( Gint)((dfp+i)->x) * p )>>12;
(otpti)->y += ( Gnt)((dfpti)->y) * p )>>12;
(otpti)->z += ( Gnt)((dfpti)->z) * p )>>12;
}
}
The argument format is as follows.
p : (1,19,12)
otp, dfp optional
Return Value
None
GsInitGraph
Graphics system initialisation
Format
void GsInitGraph (
int x res,
int y_res,
int intl,
int dither,
int vram
)
Arguments
x res Horizontal resolution (256/320/384/512/640)
y_res Vertical resolution (240/480)
intl Interlace display flag (bit 0)
0: Non-interlace
1: Interlace
Double buffer offset mode (bit 2)
0: GTE offset
1: GPU offset
dither Whether or not dither when drawing
0: OFF
1: ON
vram Frame buffer mode
0: 16bit
1: 24bit
Comments
Return Value
GsInitGraph initialises the graphics system.
The GPU setting is notified by the global variablesGsDISPENV andGsDRAWENYV, so
the program GPU setting can be confirmed and changed by referring tGsDISPENV and
GsDRAWENV.
The double buffer offset mode decides whether the double buffer offset is executed by
GTE or by GPU. It is easier to handle when executed by GPU because the double buffer
offset value is not included in the packet.
In the 24-bit mode, only image display is possible. Polygon drawing etc. is not possible.
Because initialisation of the graphics system includesGsIDMATRIX and GsIDMATRIX2
initialisation, none of the Gs * * * functions operate normally unlessGsInitGraph() has
been called.
None
GsInit3D
Format
Arguments
Comments
Return Value
Notes
See Also
3D graphics system initialisation
void GsInit3D ( void )
None
GsInit3D initialises the 3D graphics system within the library.
3D graphics system needs to be initialised by this function first, so that 3D processing
functions such as GsSetRefView(), GsInitCoordinate2() and GsSortObject4() can be used.
The following process is executed.
(1) The screen origin is held in the screen centre.
(2) The light source defaults to LIGHT NORMAL.
None
With this function, the graphics system must firstly beintialised by GsInitGraph().
GsInitGraph(), GsSetRefView(), GsInitCoordinate2(), GsSortObject4()
GsDefDisp Buff
Format
Arguments
Comments
Double buffer definition
void GsDefDisp Buff (
int x0,
int y0,
int xl,
int yl,
)
x0, yO Buffer 0 origin (top left-hand)coordinates
xl, yl Buffer 1 origin (top left-hand)coordinates
GsDefDispBuff defines the double buffer. «0, y0) and (x1,y1) are specified by the
coordinate value within the frame buffer. In default, the buffer 0 becomes (0, 0) and buffer
1 becomes (0, y_res).
y_res is the vertical resolution specified byGsInitGraph(). The double buffer is cancelled
when (x0, y0) and (x1, yl) have the same coordinate values. Switching the double buffer
of the even number field and odd number field is automatically carried out if it is left in
this mode when the interlace mode is specified.
Double buffer switching is carried out by theGsSwapDispBuff() function.
The double buffer is executed by GPU or GTE offset. GsInitGraph() sets
Return Value
See Also
whether execution of offset is by GPU or by GTE. If the double buffer is executed using
the GPU offset, the coordinate value is created in the coordinate system whose origin is
the top left-hand point of the double buffer in the packet. On the other hand, if the double
buffer is executed using the GTE offset, thecoordinate value is created in the coordinate
system whose origin is the origin (top left-hand point) of the frame buffer in the packet.
None
GsInitGraph(), GsSwapDispBuff()
GsSwapDisp Buff
Format
Arguments
Comments
Double buffer switching
void GsSwap Disp Buff( void )
None
GsSwapDispBuff changes the display buffer and drawing buffer according to double
buffer information that has been set byGsDefDispBuff(). Execution is usually carried out
immediately after vertical return section surge.
Also, the following processes are executed within the function.
(1) Display commencement address setting
(2) Cancellation of blanking
(3) Double buffer index setting
(4) 2 dimensional clipping switched
(5) GTE or GPU offset setting
(6) Offset setting
(7) PSDCNT increment
The double buffer is executed by the offset. The third argument ofGsInitGraph() decides
whether the offset is set by GTE or by GPU GSOFSGPU orGsOFSGTE is specified).
Return Value
None
Notes
If GPU is drawing, this function does not operate smoothly and it needs to be called
immediately after drawing completion has been confirmed byDrawSync(0) or after the
drawing has been ended by ResetGraph(1).
See Also
GsDefDispBuff()
GsGetActiveBuff
Gets drawing buffer number
Format
int GsGetActiveBuff( void )
Arguments
None
Comments
GsGetActiveBuff gets the double buffer index (PSDIDX). The index value is either 0 or 1.
The frame buffer top 2 dimensional address of the double buffer origin (top left
coordinate) is found by entering the index in the external variables PSDOFSX[ ] and
PSDOFSYT{ ].
Return Value
The double buffer index (0 when buffer 0 and 1 when buffer 1) is returned.
See Also
PSDIDX
GsSetDrawBuffO ffset
Format
Arguments
Comments
Return Value
Notes
See Also
Drawing offset update
void GsSetDrawBuffO ffset( void )
None
GsSetDrawBuffOffset updates the offset for drawing. The set value is represented in the
global conversion POSITION.
This offset is relative within the double buffer, and the offset value is maintained even if
the double buffer is switched.
The setting of GTE or GPU is executed if this function is called. The third argument of
GsInitGraph() decides whether the offset is executed by GTE or by GPUGsOFSGPU or
GsOFSGTE is specified).
None
This function does not operate smoothly if GPU is drawing, and it needs to be called
immediately after completion of drawing has been confirmed byDrawSync(0) or after
drawing has been ended by ResetGraph(1).
GsSetOrign(), GsSetOffset(), POSITION
GsSetO ffset
Offset setting
Format
void GsSetO ffset (
int offx,
int offy
)
Arguments
offx Drawing offset X
offy Drawing offset Y
Comments
GsSetOffset specifies the drawing offset. It is different fromGsSetDrawBuffOffset() in
that GsSetDrawBuffOffset() sets the value of the global variable POSITION, whereas
GsSetOffset() sets the offset supplied by the argument.
Also, the value set by GsSetOffset() is temporary and the offset values that are set on
execution of GsSwapDispBuff() andGsSetDrawBuffOffset() become invalid. On the other
hand, the set values of GsSetDrawBuffOffset() are valid until changed byGsSetOrigin().
The offset supplied by the argument is relative within the double buffer. In other words,
the offset actually set is the base offset of the double buffer added to the offset supplied by
the argument.
The third argument of GsInitGraph() decides whether the offset is executed by GTE or by
GPU (GsOFSGPU orGsOFSGTE is specified).
Return Value
None
Notes
This function does not operate smoothly if GPU is drawing, and it needs to be called
immediately after completion of drawing has been confirmed byDrawSync(0) or after
drawing has been ended by ResetGraph(1).
See Also
GsSetDrawBuffOffset()
GsSetDrawBuffClip
Format
Arguments
Comments
Return Value
Notes
See Also
Drawing clipping area update
void GsSetDrawBuffClip( void )
None
GsSetDrawBuffClip updates the drawing clip. It actually represents the clip value set by
GsSetClip2D(). The set value is valid until the GsSetDrawBuffClip() function is called
once more by a different clip value.
Moreover, this clip value is relative within the double buffer, and the position of the clip
does not change even if the double buffer is switched.
None
This function does not operate smoothly if GPU is drawing, and it needs to be called
immediately after completion of drawing has been confirmed byDrawSync(0) or after
drawing has been ended by ResetGraph(1).
GsSetClip2D(), GsSetClip()
GsSetC lip
Drawing clipping area setting
Format
void GsSetClip (
RECT *clip
)
Arguments
clip RECT structure for setting the clipping area
Comments
GSetClip sets the clip for drawing. The set value is valid until theGsSwapDispBuff()
function is called next. It is different fromGsSetDrawBuffClip() in that the place where
the clip area can be specified by the argument and the validity period of the set value are
different.
Moreover, this clip value is relative within the double buffer.
Return Value
None
Notes
This function does not operate smoothly if GPU is drawing, and it needs to be called
immediately after completion of drawing has been confirmed byDrawSync(0) or after
drawing has been ended by ResetGraph(1).
See Also
GsSetDrawBuffClip()
GsGetTimInfo
Checks TIM format header
Format
void GsGetTimInfo(
unsigned long *tim,
GsIMAGE “m
)
Arguments
tim TIM data top address
im Pointer to image structure
Comments
TIM format information specified by the argumentim is stored in im.
The top of the TIM data is the address that skipped the ID. In other words, it has an offset
4 bytes forward from the top of the TIM file.
For file format, please refer to the NetYaroze Members' Web site.
Return Value
None
See Also
GsIMAGE
GsMapModelingData
Format
Arguments
Comments
Return Value
Notes
Maps TMD data to an actual address
void GsMapModelingData(
unsigned long *p
)
p Top address of TMD data
The offset address from the top of the TMD data is stored because at the time of TMD
data creation it is uncertain where it is going to be loaded onto the memory.
The GsMapModelingData() function converts this offset address into an actual address,
and this conversion must be carried out first of all in order to use the TMD data.
The TMD data top address is the one that skipped the ID. In other words, it has an offset 4
bytes forward from the top of the TMD file.
For file format, please refer to the NetYaroze Members' Web site.
None
A flag stands in the TMD data converted to an actual address, so that no side effects will
occur even ifGsMapModelingData() is called for a second time.
GsLinkObject4
Format
Arguments
Comments
Return Value
Notes
See Also
Links object and TMD data
void GsLink Object4(
unsigned long *tmd,
GsDOBJ2 *obj_ base,
unsigned long n
)
tmd Top address of the linking TMD data
obj_base Array of the object structure to be linked
n Index of the linking object
GsLinkObject4 links the TMD data (nth) object with the object structure of GSDOBJ2, so
that TMD 3D objects can be handled by GsDOBJ2.
None
Objects linked by GsLinkObject4() can be registered in OT by GsSortObject4().
GsSortObject4(), GsDOBJ2
GsSetRefView2
Viewpoint position setting
Format
int GsSetRefView2 (
GsRVIEW?2 *pv
)
Arguments
pv Viewpoint position information (viewpoint: steady viewpoint
type)
Comments
GsSetRefView2 calculates the WSMATRIX (World Screen Matrix) from the viewpoint
information. If the viewpoint does not move, the WSMATRIX does not change and does
not need to be called each frame. However, when the viewpoint moves, changes are not
represented unless the WSMATRIX is called each frame.
When super of the GSRVIEW2 member is set outside WORLD, even if other parameters
are not changed, GsSetRefView2() needs to be called each frame becausehe viewpoint
moves ifthe parent coordinate system parameters change.
Return Value
0 is returned when viewpoint setting is successful, 1 when it fails.
See Also
GsRVIEW2,GsWSMATRIX, GsSetView2()
GsSet View2
Viewpoint setting
Format
int GsSet View2 (
GsVIEW2 *pv
)
Arguments
pv Viewpoint position information (matrix type)
Comments
GsSetView?2 directly sets the WSMATRIX (World Screen Matrix). If the viewpoint is
moved, errors can arise due to inaccuracy in the process that searches WSMATRIX from
the viewpoint steady viewpoint using GsSetRefView2(), and so it is advantageous to use
GsSetView2().
When super of the GSVIEW2 member is set outside WORLD, GsSetRefView2() needs to
be called each frame even if other parameters are not changed. This is becausethe
viewpoint movesunless the parent coordinate system parameters change.
The screen aspect ratio is regulated automatically if GIIDMATRIX2 is used in the basic
matrix.
Return Value
0 is returned if setting is successful, 1 if it fails.
See Also
GsVIEW2,GsWSMATRIX, GsSetRefView2()
GsSetProjection
Format
Arguments
Comments
Return Value
Projection plane position setting
void GsSetProjection (
unsigned short h
)
h Distance between viewpoint and projection plane (projection
distance),
default is 1000.
GsSetProjection regulates the field of view.
The projection is the distance from the viewpoint to the projection plane.
The size of the projection plane is set by theGsInitGraph() arguments xres, yres. The field
of view narrows if the projection distance is enlarged and expands if it is reduced, because
the size of the projection plane is fixed according to the resolution.
Be careful, because sometimes aspect ration is not | to 1, depending on the resolution. In
this case, the scale of Y coordinates is made 1/2 and the aspect ratio is adjusted.
640x480 640x240 320x240
None
GsSetF latLight
Format
Arguments
Comments
Return Value
Notes
See Also
Parallel light source setting
void GsSetF latLight (
unsigned short id,
GsF LIGHT Ät
)
id Light source number (0,1,2)
It Light source information
GsSetFlatLight sets the parallel light source. The light source can be set up to three {d =
0, 1, 2).
Light source information is given by theGsF_LIGHT structure.
None
Even if the contents of theGsF_LIGHT structure are rewritten, the setting is not
represented unless this function is called.
GsF_LIGHT, GsSetAmbient()
GsSetLightMode
Light source mode setting
Format
void GsSetLightM ode(
unsigned short mode
)
Arguments
mode Light source mode (0~1)
0: normal lighting
1: normal lighting fog ON
Comments
GsSetLightMode sets the light source mode.
The light source calculation method can also be set by the status bit (attribute) of each
object (GsDOBJ2). Setting by the status bit is used in precedence to the status setting.
Return Value
None
GsSetFogParam
Fog parameter setting
Format
void GsSetFogParam (
GsFOGPARAM “fogparam
)
Arguments
fogparam Pointer to fog parameter structure
Comments
GsSetFogParam carries out fog parameter setting. Fog is only effective if the light mode is
1.
Return Value
None
See Also
GsFOGPARAM, GsSetLightMode()
GsSetAmbient
Ambient colour setting
Format
void GsSetAmbient (
unsigned short r,
unsigned short g,
unsigned short b
)
Arguments
r, g, b RGB value of the ambient colour (0~4095)
Comments
GsSetAmbientsets ambience (ambient light). Setting is carried out in each ofr, g and b
according to what fraction of unlit parts there are to lit parts. 1/1 becomes 4096 and 1/8
becomes 4096/8.
Return Value
None
See also
GsSetFlatLight()
GsInitCoordinate2
Local coordinate system initialisation
Format
void GsInitCoordinate2(
GsCOORDINATE2 ‘super,
GsCOORDINATE2 ‘base
)
Arguments
super Pointer to parent coordinate system
base Pointer to (initialising) coordinate system
Comments
GsInitCoordinate2 initialises the localcoordinate system. Initialisation ofbase- >coord is
by the unit matrix, and base- >super by the coordinate system specified by the argument.
Return Value
None
See Also
GsCOORDINATE2
GsGetLw
Format
Arguments
Comments
Return Value
See Also
Calculates local world matrix
void GsGetLw (
GsCOORDINATE2 toord,
MATRIX *m
)
coord Pointer to local coordinate system
m Pointer to matrix
GsGetLw calculates the local world perspective conversion matrix fronvoord of the
matrix type coordinate system GSCOORDINATE2 specified by the argument and stores
the result in the MATRIX type structurem.
Also, the calculation result of each node of the hierarchicalcoordinate system is held in
order to increase speed, and calculation up to nodes that are not changed is omitted even
when the GsGetLw() function is next called.
This is controlled by the GSCOORDINATE2 flag (1 is substituted for the
GsCOORDINATE? flag after calculation). However, even when 1 is substituted for the
flag, note that calculation will be carried out if the parent node has been changed.
None
GsGetLws(), GsSetLightMatrix()
GsGetLs
Calculates local screen matrix
Format
void GsGetLs (
GsCOORDINATE2 *toord,
MATRIX *n
)
Arguments
coord Pointer to local coordinate system
m Pointer to matrix
Comments
GsGetLs calculates the perspective conversion matrix of the local screen froncoord of
the matrix type coordinate system GSCOORDINATE2 specified by the argument, and the
result is stored in the MATRIX type structurem.
Also, the calculated result of each node of the hierarchicalcoordinate system is held in
order to increase speed, and calculation up to nodes that are not changed is omitted even
when the GsGetLw() function is next called.
This is controlled by the GSCOORDINATE2 flag (1 is substituted for the
GsCOORDINATE? flag after calculation). However, even when 1 is substituted for the
flag, note that calculation will be carried out if the parent node has been changed.
Return Value
None
See Also
GsSetLsMatrix()
GsGetLws
Calculates both local world and local screen matrices
Format
void GsGetLws (
GsCOORDINATE2 toord2
MATRIX 4w,
MATRIX s
)
Arguments
coord2 Pointer to local coordinate system
lw Pointer to local worldcoordinate system
Is Pointer to local screencoordinate system
Comments
GsGetLws calculates both the local worldcoordinates and the local screencoordinates at
the same time from the localcoordinate system coord2, and stores them in lw and ls. It is
faster than continuously callingGsGetLw() and GsGetLs().
The local world matrix must be specified if light source calculation is carried out at the
time of execution, but in this case it is faster to search once withGsGetLws().
Return Value
None
See Also
GsGetLs(), GsGetWs()
GsScaleScreen
Format
Arguments
Comments
Scales screen coordinate system
void GsScaleScreen(
SVECTOR ‘scale
)
scale The scale factor (12bit fixed decimal point format)
GsScaleScreen sets the scale factor for the original screen
coordinate system normally set by GsSetView2() and
GsSetRefView2().
By entering ONE forvx, vy and vz , it returns to the original.
GsScaleScreen carries out scaling of the screencoordinate system with respect to the
world coordinate system.
Problems such as the closeness of Far Clip occur because the screencoordinate system is
only 16bit whereas the world coordinate system has a 32bit space.GsScaleScreen() is a
function that resolves this problem, carries out scaling of the screencoordinates and
covers a wider area for the worldcoordinates.
For example, the screen coordinate system expands to a 17bit equivalent size when
ONE/2 is specified in (vx,vy,vz). However, as precision is 16bit, the bottom 1 bit is
invalid.
At this time, screen coordinate systems with different scales should not be registered in
OT with the same scale. For example, registration must be carried out by shifting to one
extra bit, in order to register objects, calculated with the screencoordinate system of the
normal scaling, to the OT that registered the objects that were half the scale of the screen
coordinate system.
Return Value
None
GsSetLsMatrix
Sets local screen matrix
Format
void GsSetLsMatr ix (
MATRIX “mp
)
Arguments
mp Local screen matrix to be set
Comments
GsSetLsMatrix sets the local screen matrix in GTE.
If perspective conversion process is carried out using GTE, the local screen matrix needs
to be pre-set in GTE.
Because the GsSortObject4() function performs perspective conversion using GTE,
GetLsMatrix() needs to be called beforehand
Return Value
None
See Also
GsSortObject4(), GsGetLs()
GsSetLightMatrix
Format
Arguments
Comments
Return Value
See Also
Sets light matrix
void GsSetLightMatr ix(
MATRIX “mp
)
mp Local screen light matrix to be set
GsSetLightMatrix multiplies the matrix of three light source vectors and the local screen
light matrix mp supplied by the argument, and sets in GTE.
Depending on the type of modelling data to be handled, the GsSortObject4() function may
perform light source calculation at the time of execution. In this case too, the light matrix
needs to be pre-set using GsSetLightMatrix().
The matrix set as the GsSetLightMatrix() argument is normally the local world matrix.
None
GsSortObject4(), GsGetLw()
GsClearOt
Format
Arguments
Comments
Return Value
See Also
void GsClear Ot (
unsigned short offset,
unsigned short point,
GsOT *otp
)
offset
point
otp
Ordering table offset value
Ordering table representative value Z
Pointer to ordering table
OT initialisation
GsClearOT initialises the ordering table displayed byotp. offset is the Z value at the top
of that ordering table, and point is the Z value referred to when inserting that ordering
table into another ordering table.
Also, the length of OT must be specified in advance in order to confirm the size to be
cleared.
None
GsOT, GsDrawOt()
GsDrawOt
Format
Arguments
Comments
Notes
Return Value
See Also
Execution of drawing command allocated to OT
void GsDrawOt (
GsOT *otp
)
otp Pointer to OT
GsDrawOt starts execution of the drawing command registered in OT displayed
by otp.
GsDrawOt() immediately returns because the drawing process is carried out in the
background.
If GPU is drawing, this function does not operate smoothly and it needs to be called
immediately after drawing completion has been confirmed byDrawSync(0) or after
drawing has been ended by ResetGraph(1).
None
GsOT, GsClearOt()
GsSortObject4
Format
Arguments
Comments
void GsSortObject4 (
GsDOBJ2 *objp,
GsOT *otp,
long shift,
u_long *scratch
)
objp
otp
shift
scratch
Allocates object to ordering table
Pointer to object
Pointer to OT
How many bits the value of Z is shifted to the right at the time
of allocation to OT
Specifies scratchpad address
GsSortObject4 carries out perspective conversion and light source calculation for 3D
objects to be handled by GSDOBJ2, and generates the drawing command in the packet
area specified by GsSetWorkBase(). Next, it Z sorts the generated drawing command and
allocates it to OT displayed byotp.
The precision of Z can be adjusted by the value ofshift. The maximum value of the
ordering table size (resolution) is 14bit. However, if for example it is 12bit, then the value
of shift is 2 (=14 - 12). At this time take care not to go over the area of the ordering table.
scratch is used as work when automatic division is carried out.
In order to validate the division by attribute which is the member ofobjp, OR is carried
out by GsDIVS, which is the member of macro GsDIV lebjp defined by libps.h. One
polygon
is divided into 4 sections of 2x2 at the time of GsDIV1 and into 1024 sections of 32x32 at
the time of GsDIVS.
Also, scratchpad is cache memory and 256 words are packaged from 0x1£800000.
Return Value
None
See Also
GsDOBJ2, GsSetWorkBase()
GsSetWorkBase
Sets drawing command storage address
Format
void GsSet WorkBase(
PACKET *base_addr
)
Arguments
base_addr Address that stores the drawing command
Comments
GsSetWorkBase sets the memory address that stores the drawing primitives generated by
such functions as GsSortObject4() andGsSortSprite().
At the start of the process of each frame, it must be set in the top address of the packet
area secured by the user.
Return Value
None
See Also
GsSortObject4(), GsSortSprite(), GsSortFastSprite(), GSOUT_PACKET_P
GsGetW orkBase
Gets current drawing command storage address
Format
PACKET *GsGetW orkBase( void )
Arguments
None
Comments
GsGetWorkBase gets the current drawing primitive packet address
The top address of the unused area can be got.
Return Value
The address that creates the next drawing primitive packet
See Also
GsSetWorkBase(), GSOUT_PACKET_P
GsSortClear
Registers drawing clear command in OT
Format
void GsSortClear (
unsigned charr,
unsigned char g,
unsigned char b,
GsOT *otp
)
Arguments
r, g, b Background colour RGB Value
otp Pointer to OT
Comments
GsSortClear sets the drawing clear command at the top of OT displayed bytp.
Return Value
None
Notes
GsSortClear only registers the clear command in the ordering table, and is not executed
unless the drawing is started by the GsDrawOt() function.
GsSortSprite
Format
Arguments
Comments
Return Value
See Also
Registers sprite in OT
void GsSortSprite(
GsSPRITE ‘Sp,
GsOT *otp,
unsigned short pri
)
sp Pointer to sprite
otp Pointer to OT
pri Position in OT
GsSortSprite allocates the sprite displayed bysp to the ordering table displayed by otp.
The parameters of sprite display positions, etc. are all supplied by thesp members.
pri is the priority order on the sprite ordering table. The highest value is 0 and the lowest
value depends on the size of the ordering table. If a numerical value of the size of the
ordering table or more is specified, it is clipped to the maximum value got by the ordering
table.
None
GsOT, GsSPRITE, GsSortFastSprite()
GsSortFastSprite
Format
Arguments
Comments
Registers sprite in OT
void GsSortFastSpritd
GsSPRITE *p,
GsOT *otp,
unsigned short pri
)
sp Pointer to sprite
otp Pointer to OT
pri Position in OT
GsSortSprite allocates the sprite displayed bysp to the ordering table displayed by otp.
The parameters of sprite display positions, etc. are all supplied by thesp members.
pri is the priority order on the sprite ordering table. The highest value is 0 and the lowest
value depends on the size of the ordering table. If a numerical value of the size of the
ordering table or more is specified, it is clipped to the maximum value got by the ordering
table.
In comparison with theGsSortSprite() function, GsSortFastSprite() is processed at high
speed, although the scaling rotation function cannot be used. At this time, the value of the
sprite structure members, mx, my, scalex, scaley and rotate are disregarded.
Return Value
None
See Also
GsSortSprite(),GsSPRITE
GsInitFixBg16
Initialises high-speed BG working area
Format
void GsInitFixBg16 (
GsBG *bg,
unsigned long *work
)
Arguments
bg Pointer to GSBG
work Pointer to working area (primitive area)
Comments
GslInitFixBg16 initialises the working area used by the GsSortFixBg16 () function. The
size of the necessary array varies according to the screen resolution. The size can be found
by the following formula (unit is long).
Size = (((ScreenW/CellW+1)*(ScreenH/CellH+1+1)*6+4)*2+2)
ScreenH: Screen height vertical dot number (240/480)
ScreenW: Screen height horizontal dot number (256/320/384/5 12/640)
CellH: Cell height (pixel number)
CellW: Cell width (pixel number)
GsInitFixBg16() should only be executed once, and does not need to be executed every
frame.
Return Value
None
See Also
GsSortFixBg16()
GsSortFixBg16
Format
Arguments
Comments
Registers high-speed BG to OT
void GsSortFixBg16(
GsBG *bg,
unsigned long *work,
GsOT *otp,
unsigned short pri
)
bg Pointer to GSBG
work Pointer to working area (primitive area)
otp Pointer to OT
pri Position in OT
GsSortFixBg16 carries out BG data registration processing to the ordering table.
BG rotation/scaling/reduction not possible.
Cell size fixed (16x16).
Texture pattern colour mode 4bit/8bit only.
Map size is optional.
Scrolling possible (1 pixel unit)
Full screen only
This function needs working area for storing the drawing primitives. The working area is
prepared as an unsigned long type array, and initialisation by GsInitFixBg16() needs to be
carried out in advance.
Packet Area (the area set by GsSetWorkBase()) is not used.
Return Value
None
See Also
GsInitFixBg16()
GsSortLine
Registers straight lines to OT
Format
void GsSortLine(
GsLINE “p,
GsOT *otp,
unsigned short pri
)
Arguments
Ip Pointer to GSLINE
otp Pointer to OT
pri Position in OT
Comments
GsSortLine allocates straight lines that are displayed bylp to ordering table displayed by
otp.
Single colour straight lines are registered in OT byGsSortLine().
Return Value
None
See Also
GsSortGLine()
GsSortGLine
Format
Arguments
Comments
Return Value
See Also
Registers straight lines to OT
void GsSortGLine(
GsGLINE “4p,
GsOT *otp,
unsigned short pri
)
Ip Pointer to GSGLINE
otp Pointer to OT
pri Position in OT
GsSortGLine allocates straight lines that are displayed bylp in the ordering table
displayed by otp.
Straight lines with gradation are registered in OT byGsSortGLine().
None
GsSortLine()
GsSortBoxFill
Format
Arguments
Comments
Return Value
Registers rectangles to OT
void GsSortBoxF ill (
GsBOXF *bp,
GsOT *otp,
unsigned short pri,
)
bp Pointer to GTBOXF
otp Pointer to OT
pri Position in OT
GsSortBoxFill allocates rectangles displayed bybp to ordering table displayed by otp.
None
GsSortOt
Allocates OT to another OT
Format
GsOT *GsSortOt (
GsOT *ot_sre,
GsOT *ot_dest
)
Arguments
ot_src Pointer to assigned source OT
ot_dest Pointer to assigned destination OT
Comments
GsSortOt assigns the OT displayed byot_src to ot_dest.
The OTZ value used at this time is the representative value in theot_src point field.
The integrated OT is assigned to ot_dest.
Return Value
Pointer to integrated OT
See Also
GsOT
GsSetClip2D
2 dimensional clipping setting
Format
void GsSetClip2D(
RECT *rectp
)
Arguments
rectp Clip area
Comments
GsSetClip2D sets the area displayed byrectp as the clipping area.
This setting is not influenced by the double buffer, and so once it is set, the same area is
automatically clipped even if the double buffer is switched.
GsSetDrawBuffClip() needs to be called in order to validate this setting immediately
afterwards. IfGsSetDrawBuffClip() is not called, the setting becomes valid from the next
frame.
Return Value
None
GsSetOrign
Screen origin position setting
Format
void GsSetOrign (
int x,
int y
)
Arguments
x Screen origin position X
y Screen origin position Y
Comments
GsSetOrign specifies the drawing offset.
The offset value set by GsSetOffset() is temporary and whereas the offset set when
GsSwapDispBuff() orGsSetDrawBuffOffset() is called becomes invalid, the offset value
set by GsSetOrign() is valid until next changed byGsSetOrign().
The offset supplied by the argument is relative within the double buffer. In other words,
the offset actually set is the offset supplied by the argument added to the offset of the
double buffer base. In reality, it is set byoffx and offy of the global variable POSITION.
Notes
The third argument of GsInitGraph() decides whether the offset is executed by GTE or by
GPU (GsOFSGPU orGsOFSGTE is specified).
Return Value
None
GsIncFrame
Updates frame ID
Format
GsIncFrame)
Arguments
None
Comments
GsIncFrame is the macro called insideGsSwapDispBuff(). It applies one increment to
PSDCNT. Although PSDCNT is 32bit, it does not become 0 even if it is recycled, and it
starts from 1.
PSDCNT is referred to when the validity of the matrix cache is determined byGsGetLw(),
GsGetLs() and GsGetLws().
If the double buffer is switched without usingGsSwapDispBuff() andGsGetLw(),
GsGetLs() and GsGetLws() are used, this macro needs to be called every time the double
buffer is switched.
See Also
PSDCNT, GsGetLw(), GsGetLs(), GsGetLws(), GsSwapDispBuff()
Table: Graphics External Variables
CLIP2 RECT 2 dimensional clipping area
PSDOFSX [2] unsigned short Double buffer base point (X coordinate)
Set by GsDefDispbuff()
PSDOFSY [2] unsigned short Double buffer base point (Y coordinate)
Set by GsDefDispbuff()
GsLSMATRIX MATRIX Local screen matrix
Set by GsSetLs()
GsWSMATRIX MATRIX World screen matrix
Set by GsSetRefView(), etc.
GsLIGHT_MODE Default light mode
GsLIGHTWSMATRIX MATRIX Light matrix
Set by GsSetFlatLight()
GsIDMATRIX2 MATRIX Unit matrix (including aspect conversion)
GsOUT_PACKET_P unsigned long Pointer holding top of packet area
Set by GsSetWorkBase()
2
Sound Functions
SndVolume
Structure
struct SndVolume {
Members
left
right
unsigned short left;
unsigned short right;
L channel volume value
R channel volume value
Volume
SsVabTransfer
Recognises and transmits sound source data
Format
short SsVabTransfer (
unsigned char vh_addr,
unsigned char vb_addr,
short vabid,
short i_flag
)
Arguments
vh_addr VH data top address
vb_addr VB data top address
vabid VAB identification number
i flag Fixed at 1
Comments
SsVabTransfer recognises the sound source header list (VH data) specified byvh_addr,
and transmits the sound source data (VB data) specified byvb_addr to the SPU sound
buffer. It specifies the VAB identification number invabid. It searches and allocates an
available VAB identification number (0 - 15) whenvabid is -1.
Return Value
VAB identification number
In the case of failure, the following values are returned according to the cause.
-1 VAB ID cannot be assigned or VH abnormality
-2 VB abnormality
-3 or below Other abnormalities
See Also
SsVabClose()
SsVabC lose
Closes VAB data
Format
void SsVabClose
short vab_id
)
Arguments
vab_id VAB data id
Comments
SsVabClose closes VAB data that holdsvab_id.
Return Value
None
See Also
SsVabTransfer()
SsSeqOpen
Opens SEQ data
Format
short SsSeqOpen(
unsigned long* addr,
short vab_id
)
Arguments
addr SEQ data main memory top address
vab_id VAB id
Comments
SsSeqOpen analyses the SEQ data in the main memory, and returns the SEQ access
number.
A maximum of 32SEQ data can be opened at the same time and if more than that are
opened, -1 becomes the return value.
Return Value
SEQ access number (the number to be used within the SEQ data access function and the
number of the SEQ data control table held internally).
See Also
SsSeqClose()
SsSeqC lose
Closes SEQ data
Format
void SsSeqClose(
short seq_access_ num
)
Arguments
seq_access num SEQ access number
Comments
SsSeqClose closes the SEQ data holding theseq_acces_numthat is no longer necessary.
Return Value
None
See Also
SsSeqOpen()
SsSeqPlay
SEQ data reading (musical performance)
Format
void SsSeqPlay(
short seq_access num
char play_mode
short |_ count
)
Arguments
seq_access num SEQ access number
play_mode Performance mode
SSPLAY_ PAUSESwitches to pause state
SSPLAY PLAY Performs immediately
1 count Number of tune repetitions
Comments
According to theplay_modevalue, SsSeqPlay can select whether to begin reading
(performing) the SEQ data immediately or switch to the pause state at the SEQ data top
(tune top). At this time, it specifies the number of tune repetitions inl_count
SSPLAY_ INFINITY is specified if there is an infinite number of performances
Return Value
None
See Also
SsSeqPause(), SsPlayBack(), SsSeqStop()
SsSeqPause
Temporarily stops SEQ data reading (pause)
Format
void SsSeqPause(
short seq_access num
)
Arguments
seq_access num SEQ access number
Comments
SsSeqPausetemporarily stops the reading (performance) of SEQ data holding
seq_access num
Return Value
None
See Also
SsSeqPlay(), SsSeqReplay()
SsSeqReplay
Restarts SEQ data reading (replay)
Format
void SsSeqReplay(
short seq_access num
)
Arguments
seq_access num SEQ access number
Comments
SsSeqReplay restarts the reading of the SEQ data holdingseq_access_numthat has been
temporarily suspended by SsSeqPause.
Return Value
None
See Also
SsSeqPlay(), SsSeqPause()
SsSeqStop
Stops SEQ data reading (stop)
Format
void SsSeqStop (
short seq_access num
)
Arguments
seq_access num SEQ access number
Comments
SsSeqStop ends the reading (performance) of the SEQ data holdingseq_access_ num
Return Value
None
See Also
SsSeqPlay()
SsSeqSetVol
SEQ volume setting
Format
void SsSeqSet Vol(
short seq_access num
short voll,
short volr
)
Arguments
seq_access num SEQ access number
voll L channel main volume value
volr R channel main volume value
Comments
SsSeqSetVol sets the main volume of the tune holdingseq_access_numnmn sizes specified
in the L and R channels respectively. 0 to 127 can be set.
Return Value
None
See Also
SsSeqGetVol()
SsSeqGet Vol
Gets SEQ volume
Format
void SsSeqGet Vol(
short access_num
short seq_num,
short *voll,
short *volr
)
Arguments
access num SEQ access number
seq_num Fixed at 0
voll SEQ L volume value
volr SEQ R volume value
Comments
SsSeqGetVol returns the current L and R volume values of SEQ tooll and volr
respectively.
Return Value
None
See Also
SsSeqSetVol()
SsSeqSetNext
Next SEQ data specification
Format
void SsSeqSetNext (
short seq_access_num]
short seq_access_num2
)
Arguments
seq_access_numl SEQ access number
seq_access_num2 SEQ access number
Comments
SsSeqSetNext specifies the access numberseq_access_num2of the SEQ data next to be
performed from SEQ data holdingseq_access_num1
Return Value
None
SsSeqSetRitardando
Slows tempo
Format
void SsSeqSetRitardando(
short seq_access num
long tempo,
long v_time
)
Arguments
seq_access num SEQ access number
tempo Tune tempo
v_time Time (tick unit)
Comments
SsSeqSetRitardando slows the data holdingseq_access_numuntil resolution of tempo in
v_time
However, if the specified resolution is greater (faster) than the current resolution, the
same operation as SsSeqSetAccelerando is carried out.
Return Value
None
See Also
SsSeqSetAccelerando()
SsSeqSetAccelerando
Accelerates tempo
Format
void SsSeqSetAccelerando(
short seq_access num
long tempo,
long v_time
)
Arguments
seq_access num SEQ access number
tempo Tune tempo
v_time Time (tick unit)
Comments
SsSeqSetAccelerando accelerates the data holdingseq_access_numuntil resolution of
tempo in v_time
However, if the specified resolution is smaller (slower) than the current resolution, the
same operation as SsSeqSetRitardando is carried out.
Return Value
None
See Also
SsSeqSetRitardando()
SsSetMVol
Main volume value setting
Format
void SsSetM Vol(
short voll,
short volr
)
Arguments
voll L channel volume value
volr R channel volume value
Comments
SsSetMVol sets the main volume value involl and volr respectively. Each can be set from
0 to 127.
It is essential to set it before SEQ data is played.
Return Value
None
See Also
SsGetMVol()
SsGetM Vol
Gets main volume value
Format
void SsGetM Vol(
SndVolume *m_vol
)
Arguments
m_vol Main volume value
Comments
SsGetMVol assigns the main volume value tom_vol.
Return Value
None
See Also
SsSetMVol()
SsSetMute
Format
void SsSetMute(
char mode
)
Arguments
mode Setting mode
SS MUTE ON
SS_MUTE_OFF
Comments
SsSetMute carries out mute setting.
Return Value
None
See Also
SsGetMute()
Mute on
Mute off
Mute setting
SsGetMute
Format
char SsGetMute( void )
Comments
SsGetMute gets mute attributes.
Return Value
Mute attributes.
SS_MUTE ON Mute on
SS_MUTE_OFF Mute off
See Also
SsSetMute()
Gets mute attributes
SsPlayBack
Format
Arguments
Comments
Return Value
See Also
SEQ data reading
void SsPlayBack (
short access_num
short seq_num
short |_ count
)
access num SEQ access number
seq_ num Fixed at 0
1 count Number of tune repetitions
SsPlayBack stops the tune during the current performance, and starts performance by
returning to the top of that tune.
It specifies the number of tune repetitions inl_ count SSPLAY INFINITY is specified in
the case of an infinite number of performances.
None
SsSeqPlay()
SsSetTempo
Format
Arguments
Comments
Return Value
Sets tempo
void SsSetT empo(
short access_num
short seq_num
short tempo
)
access num SEQ access number
seq_num Fixed at 0
tempo Tune tempo
SsSetTempo sets the tempo.
This is valid if the tempo set bySsSeqPlay() is to be changed. After this function has been
called, the performance is changed to the newly set tempo and played.
None
SsIsEos
Judges whether or not in mid-performance
Format
short SsIsEos (
short access_num
short seq_num
)
Arguments
access num SEQ access number
seq_num Fixed at 0
Comments
SsIsEos judges whether or not the specified tune is in mid-performance.
Return Value
1 is returned if in mid-performance, 0 if not.
SsSetSerialAttr
CD audio attribute setting
Format
void SsSetSerialAttr (
char s_num,
char attr,
char mode
)
Arguments
s num Fixed as SS_CD
attr Attribute value
mode Setting mode
Comments
SsSetSerialAttr carries out attribute setting relating to CD audio.
attr = SS_MIX Mixing
attr = SS_REV Reverberation
mode= SS_SON attr on
mode= SS_SOFF attr off
Return Value
None
See Also
SsGetSerialAttr()
SsGetSerialAttr
Gets CD audio attribute value
Format
char SsGetSerialAttr (
char s_num,
char attr
)
Arguments
s num Fixed at SS_CD
attr Attribute
Comments
SsGetSerialAttr returns the CD audio attribute value.
attr = SS_MIX Mixing
attr = SS_REV Reverberation
Return Value
Attribute value: | is returned if on and 0 if off.
See Also
SsSetSerialAttr()
SsSetSerialVol
CD audio volume value setting
Format
void SsSetSerialVol(
short s_num,
short voll,
short volr
)
Arguments
s num Fixed as SS_CD
voll L channel volume value
volr R channel volume value
Comments
SsSetSerialVol sets the CD volume value involl and volr.
The volume value can be set from 0 to 127.
Return Value
None
See Also
SsGetSerialVol()
SsGetSerialVol
Gets CD audio volume value
Format
void SsGetSerialVol (
char s_num,
SndVolume *s_vol
)
Arguments
s num Fixed at SS_CD
s_vol CD audio volume value
Comments
SsGetSerialVol returns the CD audio volume value tos_vol.
Return Value
None
See Also
SsSetSerialVol()
SsUtKeyOn
Format
Arguments
short SsUtKeyOn (
short vabld,
short prog,
short tone,
short note,
short fine,
short voll,
short volr
)
vabId
prog
tone
note
fine
voll
volr
Keys on voice
VAB number
Program number
Tone number
Half tone unit pitch specification (note number)
Detailed pitch specification (100/127 cent specification)
Volume (left)
Volume (right)
Comments
SsUtKeyOn specifies and keys on the volume number (0 to 127), tone number (0 to 15)
and VAB number for SE, and returns the allocated voice number.
Return Value
The voice number (0 to 23) used by key-on is returned.
-1 is returned in the event of failure.
See Also
SsUtKeyOff(), SsUtA lIKeyOff()
SsUtK eyOff
Format
Arguments
Comments
Return Value
See Also
short SsUtK eyO ff(
short voice,
short vabld,
short prog,
short tone,
short note
)
voice
vabld
prog
tone
note
Keys off voice
Voice number
VAB number
Program number
Tone number
Half tone unit pitch specification (note number)
SsUtKeyOff keys off the voice that was keyed on bsUtKeyOn.
0 is returned if successful, -1 if it fails.
SsUtKeyOn(), SsUtAlIKeyOff()
SsUtPitchBend
Format
Arguments
Comments
Return Value
See Also
short SsUtPitchBend(
short voice,
short vabld,
short prog,
short note,
short pbend
)
voice
vabld
prog
note
pbend
Bends pitch
Voice number
VAB number
Program number
Half tone unit pitch specification (note number)
Pitch bend value
SsUtPitchBend bends pitch of voice keyed on bySsUtKeyOn().
0 is returned if successful, -1 if it fails.
SsUtChangePitch()
SsUtChangePitch
Format
Arguments
Comments
short SsUtChangePitch(
short voice,
short vabld,
short prog,
short old_note
short old_fine,
short new_note
short new_fine
)
voice
vabld
prog
old_note
olde_fine
new_note
new_fine
Changes pitch
Voice number
VAB number
Program number
Note number at the time of SsUtKeyOn
Detailed pitch at the time of SsUtKeyOn (note number)
Note number to be changed
Detailed pitch to be changed (note number)
SsUtChangePitch changes the pitch of the voice keyed on bySsUtKeyOn().
Return Value
0 is returned if successful, -1 if it fails.
See Also
SsUtPitchBend()
SsUtSetVVol
Sets voice volume
Format
short SsUtSetVVol(
short ve,
short voll,
short volr
)
Arguments
vc Voice number
voll Volume (left)
volr Volume (right)
Comments
SsUtSetVVol sets in detail the voice volume keyed on bySsUtKeyOn().
Return Value
0 is returned if successful, -1 if it fails.
See Also
SsUtGetVVol()
SsUtGetVVol
Gets voice volume
Format
short SsUtGet VVol(
short ve,
short *voll,
short *volr
)
Arguments
vc Voice number
voll Volume (left)
volr Volume (right)
Comments
SsUtGetVVol returns the detailed value of the voice volume keyed on bySsUtKeyOn().
Return Value
0 is returned if successful, -1 if it fails.
See Also
SsUtSetVVol()
SsUtReverbOn
Reverberation on
Format
void SsUtReverbOn( void )
Arguments
None
Comments
SsUtReverbOn turns on the reverberation with the set type and depth.
Return Value
None
See Also
SsUtReverbOff()
SsUtReverbOff
Reverberation off
Format
void SsUtReverbOff( void )
Arguments
None
Comments
SsUtReverbOff turns the reverberation off.
Return Value
None
See Also
SsUtReverbOn()
SsUtSetReverbType
Sets reverberation type
Format
short SsUtSetReverbT ype(
short type
)
Arguments
type Reverberation type
ssn roo | Rew eo
ssn nme stomo | swoon | o
* Delay time and Feedback specification by reverberation type is possible
Comments
SsUtSetReverbType sets the reverberation type.
The reverberation depth is automatically set to 0 when the reverberation type is set.
When data is left in the reverberation work area, noise appears as soon as the depth is set,
so the following procedure should be used.
Return Value
See Also
SsUtSetReverbType(SS_REV...);
SsUtReverbOn();
Takes several seconds
SsUtSetReverbDepth(64,64);
Number and type response as above
If setting is carried out correctly, the set type number is returned.
If setting is carried out incorrectly, -1 is returned.
SsUtGetReverbType(), SsUtSetReverbDepth(), SsUtSetReverbFeedback(),
SsUtSetReverbDelay()
SsUtGetReverbType
Gets reverberation type
Format
short SsUtGetReverbType( void )
Arguments
None
Comments
SsUtGetReverbType gets the current reverberation type value.
Return Value
Current reverberation type value
See Also
SsUtSetReverbType()
SsUtSetReverbDepth
Format
void SsUtSetReverbDepth(
short Idepth,
short rdepth
)
Arguments
Idepth 0~127
rdepth 0~127
Comments
SsUtSetReverbDepth sets the reverberation depth.
Return Value
None
See Also
SsUtSetReverbType()
Sets reverberation depth
SsUtSetReverbFeedback
Sets feedback amount
Format
void SsUtSetReverbFeedback(
short feedback
)
Arguments
feedback 0~127
Comments
SsUtSetReverbFeedback sets the feedback amount if the echo type reverberation is used.
Return Value
None
See Also
SsUtSetReverbType()
SsUtSetReverbDelay
Sets delay amount
Format
void SsUtSetRever bDelay(
short delay
)
Arguments
delay 0~127
Comments
SsUtSetReverbDelay sets thedelayamount if the echo and delay type reverberation is
used.
Return Value
None
See Also
SsUtSetReverbType()
SsUtAllKeyOff
Keys off all voices
Format
void SsUtAllKeyO ff(
short mode
)
Arguments
mode Always 0
Comments
SsUtAllKeyOff compulsorily keys off all voices used by the sound service.
Return Value
None
See Also
SsUtKeyOn(), SsUtKeyOff(), SsSeqPlay()
3
Standard C Functions
abs
Calculates absolute value
Format
#include <stdlib.h>
long abs (
long i
)
Arguments
i Integer value
Comments
abs calculates the absolute value of the integeri. This function is primarily for searching
the absolute value ofint type integers. However, asint type and long type have the same
meaning in R3000, on this system it is a function equivalent to labs described next.
Return Value
The absolute value of the argument is returned.
See Also
labs()
labs
Calculates absolute value
Format
#include <stdlib.h>
long labs (
longi
)
Arguments
i Integer value
Comments
labs calculates the absolute value of the integeri. On this system, it is a function
equivalent to abs described previously.
Return Value
The absolute value of the argument is returned.
See Also
abs()
atoi
Format
Arguments
Comments
Return Value
See Also
Converts character strings to integers
#include <stdlib.h>
long atoi (
const char *s
)
s Character string
atoi is the same as (long)strtol(s,(char**)NULL). On this system it is a function
equivalent to atol, which follows on next page.
The result of converting the input values to an integer is returned.
atol(), strtol()
atol
Converts character strings to integers
Format
#include <stdlib.h>
long atol(
const char *s
)
Arguments
s Character string
Comments
atol is the same as (long)strtol(s,(char**)NULL).
Return Value
The result of converting the input values to an integer is returned.
See Also
atoi(),strtol()
bzero
Pads memory blocks with zeros
Format
#include <memory.h>
void *bzero(
unsigned char *p,
intn
}
Arguments
p Pointer to write start position
n Write byte number
Comments
Writes n byte zeros from the address specified byp.
Return Value
Returns the pointer to the address where write starts.
See Also
beopy(), bemp()
bcopy
Format
Arguments
Comments
Return Value
See Also
#include <memory.h>
void bcopy(
char *src,
char *dest,
longn
)
src Copy source
dest Copy destination
n Copy byte number
bcopy copies the firstn byte of src to dest.
None
memepy()
Copies memory blocks
bemp
Format
Arguments
Comments
Return Value
#include <memory.h>
long bemp(
char *b1,
char *b2,
longn
)
bl Comparison source 1
b2 Comparison source 2
n Comparison byte number
bcmp compares the firstn bytes ofb1 and b2.
Compares memory blocks
The next value depending on the comparison result ofb1 and b2 is returned.
Result Return Value
bl<b2 <0
bl=b2
b1>b2
See Also
mememp()
bsearch
Carries out binary searches
Format
#include <stdlib.h>
void *bsearch (
const void *key,
const void *base,
size_tn,
size_t w,
long(*femp)(const void *, const void *)
)
Arguments
key Storage destination of retrieved value
base Storage destination of retrieved array
n Number of elements
Ww Size of 1 element
femp Comparison function
Comments
With femp as a comparison function, bsearch carries out a binary search of tables ofn
items (size of item =w) starting from base, looking for items matchingkey.
Return Value
The address of the first item matching the retrieval key is returned. 0 is returned if there is
no matching item.
calloc
Allocates main memory
Format
#include <stdlib.h>
void *calloc (
size_tn,
size_ts
)
Arguments
n Number of articles
s Block size
Comments
calloc secures then x s byte block from the heap memory.
Return Value
The pointer to the secured memory block is returned.
NULL is returned in the event of failure.
See Also
malloc(), realloc(), free()
malloc
Allocates main memory
Format
#include <stdlib.h>
void *malloc (
size_ts
)
Arguments
s Characters to be tested
Comments
malloc secures the s byte block from the heap memory.
Return Value
The pointer to the secured memory block is returned.
NULL is returned in the event of failure to secure.
* At the time of user program activation the heap memory is defined as follows.
Lowest address Module’s highest address + 4
Highest address Package memory% 64KB
See Also
calloc(), realloc(), free()
realloc
Format
Arguments
Comments
Return Value
See Also
Reallocates heap memory
#include <stdlib.h>
void *realloc (
void *block,
size ts
)
block Area to be reallocated
s Area size
realloc reduces or enlarges the blockblock that was previously secured tos byte. Ifblock
is NULL, it has the same operation asmalloc().
The reallocated block address is returned. This address may be different from the original
address. NULL is returned in the event of failure to allocate. At this time the original
block cannot be opened.
calloc(), malloc(), free()
free
Opens allocated memory blocks
Format
#include <stdlib.h>
void free (
void*block
)
Arguments
block Area to be opened
Comments
free opens the memory block secured bycalloc(), malloc() and realloc().
Return Value
None
See Also
calloc(), malloc(), realloc()
memchr
Searches for characters in memory blocks
Format
#include <memory.h>
void *memchr (
const void *s,
long c,
size tn
)
Arguments
s Retrieved characters storage destination
c Retrieved characters
n Number of retrieved bytes
Comments
memchr locates the first appearance of the characterc in the memory block of then byte
starting from s.
Return Value
The pointer to the located character is returned. NULL is returned whence cannot be
discovered.
memcmp
Carries out memory block comparison
Format
#include <memory.h>
long memcmp (
const void *s1,
const void *s2,
size tn
)
Arguments
sl Comparison source 1
s2 Comparison source 2
n Comparison byte number
Comments
memcmp compares the firstn bytes ofs1 and s2.
Return Value
The following values are returned depending on the comparison result of§1 and s2.
Result Return Value
Poe | a
sl=s2
sl>s2
See Also
bemp()
memcpy
Format
Arguments
Comments
Return Value
See Also
#include <memory.h>
void *memcpy(
void *dest,
const void *src,
size tn
)
dest Copy destination
src Copy source
n Copy byte number
memcpy copies the firstn byte of src to dest.
dest is returned.
beopy()
Copies memory blocks
memmove
Copies memory blocks
Format
#include <memory.h>
void *memmove(
void *dest,
const void *src,
size tn
)
Arguments
~ dest Copy destination
src Copy source
n Copy byte number
Comments
memmove copies the firstn byte ofsrc to dest.
Accurate copying is performed even among duplicated objects.
Return Value
dest is returned.
memset
Writes specified characters to memory blocks
Format
#include <memory.h>
void *memset (
const void *s,
long c,
size tn
)
Arguments
s Memory block
c Character
n Character number
Comments
memset writes c to the n byte memory block starting froms.
Return Value
s is returned.
qsort
Carries out quick sort
Format
#include <stdlib.h>
void qsort (
void *base,
size_tn,
size_t w,
long (*femp)(const void *, const void *)
)
Arguments
base Storage destination of array to be sorted
n Number of elements
w Size of 1 element
femp Comparison function
Comments
With femp as a comparison function, qsort sorts a table ofn number of items (size of item
= w) starting from base.
Take care with the empty heap area becausemalloc() is called internally.
Return Value
None
srand
Initialises random number generator
Format
#include <stdlib.h>
void srand (
unsigned int seed
)
Arguments
seed Random number
Comments
srand sets the new starting point of the random number generation. Default is 1.
Return Value
None
See Also
rand()
rand
Generates random numbers
Format
#include <stdlib.h>
long rand ( void )
Arguments
None
Comments
rand generates pseudo random numbers between RAND_ MAX(0x7FFF=32767) from 0.
Return Value
A generated pseudo random number is returned.
See Also
srand()
strcat
Format
Arguments
Comments
Return Value
See Also
Adds one character string to another
#include <strings.h>
char *strcat (
char *dest,
const char *sre
)
dest Link destination character string
src Link source character string
strcat adds src to the end of the character string dest.
dest is returned.
strncat()
strchr
Format
Arguments
Comments
Return Value
Searches for position of first appearance of a specified
character in a character string
#include <strings.h>
char *strchr (
const char *s,
long c
)
s Retrieved character string
c Retrieved character
strchr searches for the position where the characterc first appears in the character string s.
The address of the appearance position ofc is returned. NULL is returned ifc does not
appear.
strcmp
Compares character strings
Format
#include <strings.h>
long strcmp (
const char *s1,
const char *s2
)
Arguments
sl Comparison source 1
s2 Comparison source 2
Comments
stremp compares each character ofs1 and s2 as unsigned char.
Return Value
The following values are returned depending on the comparison result of§1 and s2.
Return Value
ee a
>0
strcpy
Format
Arguments
Comments
Return Value
See Also
Copies one character string to another
#include <strings.h>
char *strcepy (
char *dest,
const char *sre
)
dest Copy destination character string
src Copy source character string
strcpy copies src to the character string dest.
dest is returned.
strncpy()
strcspn
Format
Arguments
Comments
Return Value
Searches for first part of a character string comprising only
characters not included in specified character set
#include <strings.h>
size_t strespn (
const char *s1,
const char *s2
)
sl Character string
s2 Character group
strespn returns the length of the first part of a character string comprising only characters
not included in the character string s2 within the character string s1.
The length of the found section of the character string is returned.
strlen
Finds the number of characters in character string
Format
#include <strings.h>
long strlen (
const char *s
)
Arguments
s Character string
Comments
strlen counts number of characters in the character strings.
Return Value
The character number is returned.
strncat
Adds one character string to another
Format
#include <strings.h>
char *strncat (
char *dest,
const char *src,
size tn
)
Arguments
dest Link destination array
src Link source character string
n Link character number
Comments
strncat adds the largest n character from src to end of character string dest.
Return Value
dest is returned.
strncmp
Compares character strings
Format
#include <strings.h>
long stncmp (
const char *s1,
const char *s2,
size tn
)
Arguments
sl Comparison source 1
s2 Comparison source 2
n Comparison character number
Comments
strncmp compares as unsigned char all characters as far ass1 and s2 top n characters.
Return Value
The following values are returned depending on the result of the comparison.
Return
Result
sl=s2
sl>s2 >0
strncpy
Copies one character to another
Format
#include <strings.h>
char *strncpy(
char *dest,
const char *src,
size tn
)
Arguments
dest Copy destination character string
src Copy source character string
n Copy byte number
Comments
strncpy copies n bytes ofsrc to the character string dest. It stops copying when the number
of characters added reaches n.
Return Value
dest is returned.
strpbrk
Format
Arguments
Comments
Return Value
Searches for position of first appearance of a specified
character in a character set
#include <strings.h>
char *strpbrk (
const char *s1,
const char *s2
)
sl Retrieved character string
s2 Character group
strpbrk checks the character strings1 and searches the position where any one character
included in the character group s2 first appears.
The address of the found character is returned. NULL is returned if it is not found.
strrchr
Format
Arguments
Comments
Return Value
Searches for position of last appearance of a specified
character in a character string
#include <strings.h>
char *strrchr (
const char *s,
long c
)
s Retrieved character string
c Retrieved character
strrchr searches the position where the characterc last appears in the character string s.
The address of the appearance position ofc is returned. NULL is returned ifc does not
appear.
strspn
Format
Arguments
Comments
Return Value
Searches for first part of a character string comprising only
characters in a specified character set
#include <strings.h>
size_t strspn (
const char *s1,
const char *s2
)
sl Retrieved character string
s2 Character group
strspn returns the length of the first section that comprises only characters that are
included in the character group s2 within the character string s1.
The length of the found section of the character string is returned.
strstr
Format
Arguments
Comments
Return Value
Searches for position of appearance of specified partial
character string
#include <strings.h>
char *strstr (
const char *s1,
const char *s2
)
sl Retrieved character string
s2 Retrieved character string
strstr checks the character strings1 and searches the position where the character strings2
first appears.
The address of the position found is returned. NULL is returned if it is not found.
strtok
Format
Arguments
Comments
Return Value
Searches for a character string bounded by characters ina
specified character set
#include <strings.h>
char *strtok (
char *s1,
const char *s2
)
sl Retrieved character string
s2 Bounded character group
strtok takes the character string s1 as a set of tokens bounded by one or more characters
within the separate character string s2.
The first token top address ofs1 is returned when strtok is first called, and directly after
the token, the character NULL is written. After thes1 address is stored in the function,
when NULL is entered in the first argument andstrtok is called, a search is carried out
until the token in the character string s1 disappears.
The top address of the tokens found ins1 is returned. NULL is returned if nothing is
found.
strtol
Converts character strings to integers
Format
#include <stdlib.h>
long strtol (
const char *s,
char **endp
)
Arguments
s Character string
endp Storage destination of pointer to non-convertible character
string
Comments
strtol converts the character strings to long type (same asint type in R3000).
s must be in the following format.
[ws][sn][ddd]
[ws] White space (can be omitted)
[sn] Sign (can be omitted)
[ddd] Number string (can be omitted)
strtol stops conversion when a character is encountered that cannot be converted and,
unless endpis NULL, it sets the pointer to the character that stopped conversion toendp.
Return Value
The result of converting the input values to an integer is returned. 0 is returned when an
error occurs.
See Also
strtoul()
strtoul
Converts character string into unsigned integer
Format
#include <stdlib.h>
unsigned long strtoul (
const char *s,
char **endp
)
Arguments
s Character string
endp Storage destination of pointer to non-convertible character
string
Comments
strtoul converts the character strings to unsigned long type (same as unsignedint type in
R3000).
s must be in the following format.
[ws][sn][ddd]
[ws] White space (can be omitted)
[sn] Sign (can be omitted)
[ddd] Number string (can be omitted)
strtoul stops conversion when a character is encountered that cannot be converted and,
unless endpis NULL, it sets the pointer to the character that stopped conversion toendp.
Return Value
The result of converting the input values to an integer is returned.
See Also
strtol()
isXXX
Format
Arguments
Comments
#include <ctype.h>
long isXXX (
long c
)
Carries out character testing
Character
isXXX carries out testing of characterc. They are all macros. The test conditions are as
follows.
Function Name
isalnum
isalpha
isascii
iscntrl
isdigit
isgraph
islower
isprint
ispunct
isspace
isupper
isxdigit
Printable characters except spaces
Printable characters including spaces
Printable characters except spaces, English letters and numbers
Spaces, page breaks, line feeds, character returns, tabs
Upper case letters
Hexadecimal
Return Value
A value other than 0 is returned if the input valuec satisfies the conditions, and 0 is
returned if the conditions are not satisfied.
toascii
Masks 7th bit of an input value
Format
#include <ctype.h>
long toascii (
long c
)
Arguments
c Input value
Comments
toascii is a macro for masking the 7th bit.
Return Value
The value masking the 7th bit of the input valuec is returned.
tolower
Converts characters to lower case characters
Format
#include <ctype.h>
long tolower (
long c
)
Arguments
c Input value
Comments
tolower is a macro for converting the input valuec to a lower case character.
Return Value
The lower case character corresponding to the input valuec.
toupper
Converts characters to upper case characters
Format
#include <ctype.h>
long toupper (
long c
)
Arguments
c Input value 1
Comments
toupper is a macro for converting the input valuec to an upper case character.
Return Value
The upper case character corresponding to the input valuec.
getc
Format
Arguments
Comments
Return Value
See Also
Gets a single character from the stream
#include <stdio.h>
char gete (
FILE *stream
)
stream Input stream
Gets a single character from input streamstream.
NULL is returned in the case of file end or error.
getchar(), gets()
getchar
Format
Arguments
Comments
Return Value
See Also
Gets a single character from the standard input stream
#include <stdio.h>
char getchar( void )
None
getchar gets a single character from the standard input stream. It is the same asgetc
(stdin).
Same as getc.
getc(), gets()
gets
Reads in a character string from the standard input stream
Format
#include <stdio.h>
char *gets (
char *s
)
Arguments
s Input array storage destination
Comments
gets reads in the array that ends with a line feed character from the standard input stream
(stdin) and stores it in s.
Return Value
The character string arguments is returned when successful. NULL is returned in the case
of file end or error.
See Also
getc(), getchar()
pute
Outputs a single character to the stream
Format
#include <stdio.h>
void putc (
long c,
FILE *stream
)
Arguments
c Output character
stream Output stream
Comments
putc outputs the character c to the output stream stream
Return Value
None
See Also
putchar(), puts()
putchar
Format
Arguments
Comments
Return Value
See Also
Outputs a single character to standard output stream
#include <stdio.h>
long putchar(
char c,
)
c Output character
putchar outputs a single character to the standard output stream. It is the same as putc
(stdout).
None
putc(), puts()
puts
Outputs a character string to the standard output stream
Format
#include <stdio.h>
void puts (
const char *s
)
Arguments
s Output character string
Comments
puts outputs the character string closed by NULL to the standard output stream (stdout),
and finally outputs the line feed character.
Return Value
None
See Also
putc(), putchar()
printf
Carries out formatted output to standard output stdout
Format
#include <stdio.h>
long printf (
const char *fmt[,argument ...]
)
Arguments
fmt Input format character string
Comments
Please refer to C language reference books for a detailed explanation of input format.
Not compatible with conversion specifiers “f’, “e”, “E”, “g” and “G”.
printf2() of the mathematical function service is used in floating-point display.
Return Value
The length of the output character string is returned. NULL is returned when an error
occurs.
See Also
sprintf(), printf2()
sprintf
Format
Arguments
Comments
Return Value
See Also
Format output to array
#include <stdio.h>
long sprintf
char *s,
const char *fmt[,argument...]
)
s Storage destination of conversion character string
fmt Input format character string
Please refer to C language reference books for a detailed explanation of input format.
Not compatible with conversion specifiers “f’, “e”, “E”, “g” and “G”.
sprintf2() of the mathematical function service is used in floating-point display.
The length of the output character string is returned. NULL is returned when an error
occurs.
printf(), sprintf2()
setjmp
Defines arrival point of non-local jump
Format
#include <setjmp.h>
int setjmp (
jmp_bufp
)
Arguments
p Environment evacuation variable
Comments
Stores non-local jump arrival point information inp. When longjmp(p,val) is executed, it
returns from setjmp().
Return Value
With direct calling 0 is returned.
When jump is carried out the value supplied to the second argument of longjmp() is
returned.
See Also
longjmp()
longjmp
Format
Arguments
Comments
Return Value
See Also
#include <setjmp.h>
void longjmp (
jmp_bufp,
int val
)
p Environment evacuation variable
val Return value of setjmp()
Jumps non-locally to arrival point specified byp.
None. Not returned when executed normally.
setjmp()
Non-local jump
4
Mathematical Functions
fabs
Format
Arguments
Comments
Return Value
Notes
fabs (
double x
)
xX Floating-point value
fabs looks for the absolute value.
The absolute value ofx
This is a macro
Absolute value (macro)
atof
Converts character strings to floating-point numbers
Format
double atof(
const char *s
)
Arguments
s Character string
Comments
atof converts character string to floating-point numbers (double type).
Return Value
The result of converting the input values to double type is returned. If the correct value
exceeds the range that can be expressed, either +HUGE_VAL(1.797693 1348623 16e+308)
or -HUGE_VAL is returned according to the sign. 0 is returned if an underflow occurs.
Notes
Error processing is as follows.
Outside the range that can +/- HUGE_VAL Domain error
be expressed
Underflow occurrence = eee Domain error
See Also
strtod()
strtod
Converts character strings to floating-point numbers
Format
double strtod(
const char *s,
char **endp
)
Arguments
s Character string
endp Storage destination of pointer to non-convertible character
string
Comments
strtod converts the character strings to double type.
s must be in the following format.
[ws][sn][ddd]
[ws] White space (can be omitted)
[sn] Sign (can be omitted)
[ddd] Number string (can be omitted)
strtod stops conversion when a character is encountered that cannot be converted and,
unless endpis NULL, it sets the pointer to the character that stopped conversion toendp.
Return Value
Notes
The result of converting the input values to double type is returned. If the correct value
exceeds the range that can be expressed, either +HUGE_VAL(1.797693 1348623 16e+308)
or -HUGE_VAL is returned, according to the sign. 0 is returned if an underflow occurs.
Error processing is as follows.
Outside the range that can +/- HUGE_VAL Domain error
be expressed
Underflow occurrence a Domain error
pow
Format
Arguments
Comments
Return Value
Notes
double pow (
double x,
double y
)
x Number value
y Power
pow calculates x to the power ofy.
x to the power ofy (x)
Error processing is as follows.
x to the power of y
x<0 && “y is not Integer value”
See Also
exp()
exp
Format
Arguments
Comments
Return Value
See Also
double exp (
double x
)
xX Floating-point value
exp looks for the exponent function ofx.
e to the power of x (e”)
pow(), log()
Exponent
log
Natural logarithm
Format
double log (
double x
)
Arguments
xX Logarithm calculated value
Comments
log looks for the logarithm function ofx.
Return Value
x logarithm ( ln(x) )
Notes
x is greater than 0. Range error in the case of others.
See Also
exp(), log100
log10
Base 10 logarithm
Format
double log10 (
double x
)
Arguments
xX Logarithm calculated value
Comments
log looks for the base 10 logarithm function ofx.
Return Value
x base 10 logarithm ( log10(x) )
Notes
x is greater than 0. Range error in the case of others.
O o | Domne
See Also
log0
floor
Structure
Arguments
Comments
Return value
See Also
Largest integer not greater than x (base function)
double floor (
double x
)
x Floating-point value
floor looks for the largest integer (double type) that is not greater thanx.
Largest integer (double type) that is not greater thanx
ceil()
ceil
Smallest integer not smaller than x (ceiling function)
Structure
double ceil (
double x
)
Arguments
x Floating-point value
Comments
ceil looks for the smallest integer (double type) that is not smaller thanx.
Return value
Smallest integer (double type) that is not smaller than x
See Also
floor()
fmod
Structure
Arguments
Comments
Return value
Notes
double fmod (
double x,
double y
)
x/y floating-point number remainder
Floating-point value
Floating-point value
fmod looks for the remainder of the floating-point number resulting fronx/y.
Floating-point number remainder ofx/y
Return value sign is the same as x. 0 is returned if y is 0.
modf
Separation into integer parts and fractional parts
Structure
double modf (
double x,
double *y
)
Arguments
x Floating-point value
y Pointer to the buffer for storing integer part
Comments
modf separates x into integer parts and fractional parts.
The integer part is stored in y, and the fractional part becomes the return value.
Return value
Fractional part of x
Notes
The sign for both integer parts and fractional parts is the same asx.
sin
Sine
Structure
double sin (
double x
)
Arguments
x Angle in radian units
Comments
sin looks for the sine function ofx.
Return value
sine function ofx (sin(x))
See Also
cos(), tan(), asin()
cos
Cosine
Structure
double cos (
double x
)
Arguments
x Angle in radian units
Comments
cos looks for the cosine function ofx.
Return value
cosine function ofx (cos(x) )
See Also
sin(), tan(), acos()
tan
Tangent
Structure
double tan (
double x
)
Arguments
x Angle in radian units
Comments
tan looks for the tangent function ofx.
Return value
tangent function ofx (tan(x) )
See Also
sin(), cos(), atan()
asin
Structure
Arguments
Comments
Return value
Notes
See Also
double asin (
double x
)
xX Arcsine calculation value. Range is [-1 to 1].
asin looks for the arcsine function ofx.
Arcsine function ofx. The range is [-pi/2, pi/2].
Error processing is as follows.
[ ] shows the closed area.
sin(), acos(), atan()
Arcsine
acos
Structure
Arguments
Comments
Return value
Notes
See Also
double acos (
double x
)
x Arccosine calculation value. Range is [-1 to 1].
acos looks for the arccosine function ofx
Arccosine function ofx. The range is [0 to pi].
Error processing is as follows.
[ ] shows the closed area.
cos(), asin(), atan()
Arccosine
atan
Structure
double atan (
double x
)
Arguments
x Arctangent calculation value
Comments
atan looks for the arctangent function ofx.
Return value
Arctangent function ofx. The range is [-pi/2 to pi/2]
Notes
[ ] shows the closed area.
See Also
tan(), asin(), acos(), atan2()
Arctangent
atan2
Arctangent
Structure
double atan2 (
double x,
double y
)
Arguments
xX Floating-point value
y Floating-point value
Comments
atan2 looks for the arctangent function ofx/y.
Return value
Arctangent function ofx/y. The range is [-pi to pi].
Error processing is as follows.
x==0 && y==0 fo Domain error
Notes
[ ] shows the closed area.
See Also
atan()
sinh
Hyperbolic sine
Structure
double sinh (
double x
)
Arguments
x Angle in radian units
Comments
sinh looks for the hyperbolic sine function ofx.
Return value
Hyperbolic sine function ofx ( sinh(x) )
See Also
cosh(), tanh()
cosh
Structure
double cosh (
double x
)
Arguments
x Angle in radian units
Comments
cosh looks for the hyperbolic cosine function ok.
Return value
hyperbolic cosine function ofx ( cosh(x) )
See Also
sinh(), tanh()
Hyperbolic cosine
tanh
Structure
double tanh (
double x
)
Arguments
x Angle in radian units
Comments
tanh looks for the hyperbolic tangent function ofx.
Return value
Hyperbolic tangent function ofx ( tanh(x) )
See Also
sinh(), cosh()
Hyperbolic tangent
sqrt
Square root
Structure
double sqrt (
double x
)
Arguments
x Floating-point value that is not negative
Comments
sqrt looks for the square root ofx
Return value
Square root ofx
Error processing is as follows.
hypot
Complex number absolute value
Structure
double hypot (
double x,
double y
)
Arguments
x Floating-point value
y Floating-point value
Comments
hypot looks for the absolute value of the complex number tty).
Return value
Square root of the sum of x? and y?
Idexp
Calculates real number from mantissa and exponent (x x2")
Structure
double Idexp (
double x,
longn
)
Arguments
x Floating-point value
n Integer exponent
Comments
Idexp calculates the real number from the mantissa and exponent.
Return value
The value of x x 2"
frexp
Structure
Arguments
Comments
Return value
Notes
Resolution into normalised fractional part and 2" part
double frexp (
double x,
int *n
)
x Floating-point value
n Pointer to the buffer that stores the 2” part
frexp resolves x into fractional parts normalised to [1/2,1) and 2” parts. The fractional
part becomes the return value and the 2” part is stored in n.
Normalised fractional part [1/2, 1)
[ ] shows the closing section and () the opening section.
printf2
Formatted output of standard output stdout (supports float and double
type)
Structure
long printf2(
const char *fmt, [argument...]
)
Arguments
fmt Output format character string
Comments
The conversion specifiers “f”, “e”, “E”, “g” and “G” can be used.
The stack consumption amount is greater than printf.
Return value
The length of the output character string is returned.
See Also
sprintf2()
sprintf2
Formatted output to array (supports float and double type)
Structure
long sprintf2(
char *s,
const char *fmt, [argument...]
)
Arguments
s Storage destination of converted character string
fmt Output format character string
Comments
The conversion specifiers “f’, “e”, “E”, “g” and “G” can be used.
The stack consumption amount is greater than printf.
Return value
The length of the output character string is returned.
See Also
printf2()
5
Other Functions
EXEC
Executable file data structure
Structure
struct EXEC {
unsigned long pc0;
unsigned long gp0;
unsigned long t_addr;
unsigned long t_size;
unsigned long d_addr;
unsigned long d_ size;
unsigned long s_addr;
unsigned long s_ size;
unsigned long sp, fp, gp, base;
3
Members
pc0 Execution start address
gp0 gp register initial value
t_addr Data session top address with text session + initial value
t_size Data session size with text session + initial value
d_addr Reserved for the system
d_size Reserved for the system
b_addr Data session top address without initial value
b_size Data session size without initial value
s_addr Stack area top address (for user specification)
S_size Stack area size (for user specifiation)
sp,fp,gp,base Register evacuation area
Comments
EXEC is arranged in the top 2k bytes of the executable file (PS-X EXE structure). It holds
information for loading and executing the program that is stored in the file.
It activates the program by adding stack information and delivering it to the Exec()
function.
See Also
Exec()
DIRENTRY
Directory entry data structure
Structure
struct DIRENTRY {
char name20];
long attr;
long size;
struct DIRENTRY next
long head;
char systen{8];
}
Members
name Filename
attr Attribute (depends on file system)
size File size (byte units)
next Next file entry (for user)
head Head sector
system Reserved for the system
Comments
DIRENTRY stores information relating to files that are registered in the file system.
See Also
firstfile(), nextfileQ)
CdlILOC
Structure
Members
Comments
Notes
typedef struct {
u_char minute
u_char second
u_char sector;
u_char track
} CdILOC;
minute Minute
second Second
sector Sector
track Track number
CD location specification structure.
track members are not currently used.
CD-ROM location
CdlFILE
ISO-9660 file descriptor
Structure
typedef struct {
CdILOC pos;
u_long size;
char name 16];
} CdIFILE;
Members
pos File position
size File size
name Filename
Comments
CdIFILE gets the ISO-9660 CD-ROM file location and size.
GetRCnt
Getting root counter
Structure
long GetRCnt (
unsigned long spec
)
Arguments
spec Root counter specification
Comments
GetRCnt returns the current value of the root counterspec.
Return value
The counter value that is expanded without the sign in 32bit is returned when successful,
and -1 is returned in the event of failure.
See Also
StartRCnt(), ResetRCnt()
ResetRCnt
Resetting root counter
Structure
long ResetRCnt(
unsigned long spec
)
Arguments
spec Root counter specification
Comments
ResetRCnt resets the root counterspec.
Return value
1 is returned when successful, and 0 in the event of failure.
See Also
GetRCnt(), StartRCnt()
StartRCnt
Root counter activation
Structure
long StartRCnt (
unsigned long spec
)
Arguments
spec Root counter specification
Comments
StartRCnt activates the root counterspec.
Return value
1 is returned when successful, and 0 in the event of failure.
See Also
GetRCnt(), ResetRCnt()
Enter/ExitCriticalSection
Interruption inhibited/permitted
Structure
void EnterCriticalSection(void)
void ExitCriticalSection(void)
Arguments
None
Comments
EnterCriticalSection() inhibits interruption
ExitCriticalSection() permits interruption.
Return value
None
open
Opening file
Structure
int open (
char *devname
int flag
)
Arguments
devname Filename
flag Open mode
Comments
open opens the file devnameand returns its descriptor.
Macros that can be specified in flag are as follows.
O_NOBUF No buffer mode
O_NOWAIT No synchronisation mode
Return value
The file descriptor is returned when successful, and -1 in the event of failure.
See Also
close()
close
Closing file
Structure
int close (
int fd
)
Arguments
fd File descriptor
Comments
close releases the file descriptor.
Return value
fd is returned when successful, and -1 in all other cases.
See Also
open()
lseek
Moving file pointer
Structure
int Iseek (
int fd,
unsigned int offset,
int flag
)
Arguments
fd File descriptor
offset Offset
flag Refer to the comments
Comments
Iseek moves the file pointer of the device showing the descriptor specified byfd.
offset is the movement byte number. The movement start point changes according to the
value of flag.
It cannot be applied to character type drivers.
Macros that can be specified in flag are as follows.
SEEK _SET Top of file
Return value
The current file pointer is returned when successful, and -1 in all other cases.
See Also
open(), read(), write()
read
Reads data from file
Structure
int read (
int fd,
char *buf,
intn
)
Arguments
fd File descriptor
buf Read buffer address
n Read byte number
Comments
read reads n bytes from the descriptor specified byfd to the buf specified area.
Return value
The byte number read in the area at the time of normal termination is returned, and -1 in
all other cases.
See Also
open()
write
Writes data to file
Structure
int write (
int fd,
char *buf
intn
)
Arguments
fd File descriptor
buf Write data address
n Write byte number
Comments
write writes n bytes from the descriptor specified byfd to the buf specified area.
Return value
The byte number written in the area at the time of normal termination is returned, and -1
in all other cases.
See Also
open()
fir stfile
Structure
Arguments
Comments
Return value
Notes
See Also
First file retrieval
struct DIRENTRY “*firstfile (
char *name,
struct DIRENTRY ‘dir
)
name Filename
dir Buffer that stores information relating to retriewble files
firstfile retrieves files corresponding to the filename patternname, and stores information
relating to them in dir.
dir is returned when successful, and 0 in all other cases.
(one optional character) * (entire character string of optional length) can be used as a
wildcard character in the filename pattern. The character specification after * is
disregarded.
DIRENTRY structure, nextfile()
nextfile
Structure
Arguments
Comments
Return value
Notes
See Also
Next file retrieval
struct DIRENTRY *nexttfile (
struct DIRENTRY ‘dir
)
dir Buffer that stores information relating to retrievable files
nextfile continuously carries out retrieval in the same way as the firstfile() function
executed directly before. When relevant files are found, information relating to them is
stored in dir.
dir is returned when successful, and 0 in all other cases.
Execution will be unsuccessful if the CD-ROM drive shell cover is opened after firstfile(),
and there will be a report that the file cannot be found.
DIRENTRY structure, firstfile()
delete
Deletes files
Structure
int delete (
char *name
)
Arguments
name Filename
Comments
delete deletes the file name.
Return value
1 is returned when successful, and 0 in all other cases.
format
Structure
Arguments
Comments
Return value
Notes
int format (
char *fs
)
fs File system name
format initialises the file system fs.
1 is returned when successful, and 0 in all other cases.
Valid only for file systems that can be written.
Initialises file system
rename
Structure
Arguments
Comments
Return value
Notes
Renaming files
int rename (
char *src,
char *dest
)
src Source filename
dest New filename
rename changes the filename fromsrc to dest. It specifies the full path from the device
name to both src and dest.
1 is returned when successful, and 0 in all other cases.
Valid only for file systems that can be written.
LoadTest
Load test execution
Structure
long LoadTest (
char *name,
struct EXEC *exec
)
Arguments
name Filename
exec Executable file information
Comments
LoadTest writes the information contained in the PS-EXE format filmame to exec.
Return value
The execution start address is returned when successful, and 0 if unsuccessful.
See Also
EXEC structure, Load()
Load
Loading executable file
Structure
long Load (
char *name
struct EXEC *exec
)
Arguments
name Filename
exec Executable file information
Comments
Load reads the PS-EXE format filename in the address specified by its internal header,
and writes the internal information toexec.
Return value
1 is returned when successful, and 0 if unsuccessful.
See Also
EXEC structure, Exec()
Exec
Structure
Arguments
Comments
Executing executable files
long Exec (
struct EXEC *exec,
long argc,
char *argv
)
exec Executable file information
argc Argument number
argv Argument
Exec executes the module loaded on the memory in accordance with the executable file
information specified byexec.
Neither the stack nor the frame buffer are set ifexec->s_addr is 0.
The contents of the operation are as follows.
a)
(2)
(3)
(4)
(5)
Data session is zero cleared without an initial value.
sp, fp and gp are initialised after evacuation (the value of fp is equal to
that of sp)
The argument of main() is set (by the a0 and al registers)
The execution start address is called.
sp, fp and gp are returned after return.
Return value
1 is returned when successful, and 0 in the event of failure.
Notes
Must be executed by critical section.
See Also
EXEC structure, Load()
InitHeap
Structure
Arguments
Comments
Return value
Notes
See Also
void InitHeap (
void *head,
long size
)
head
size
Initialisation of heap area
Heap head address
Heap size (multiples of 4 byte units)
InitHeap initialises the group of memory control functions. Thereafter, malloc(), etc. can
be used. Not all the size bytes can be used because of the presence of overhead.
None
Do not carry out multiple execution.
malloc()
FlushCache
Flushing | cache
Structure
void FlushCache ( void )
Arguments
None
Comments
FlushCache flushes the I cache.
It is executed when the program code is written in the memory.
Return value
None
Notes
Memory content cannot be changed.
_get_errno
Structure
Arguments
Comments
Return value
Gets adjacent input/output error code
long _get_errno ( void )
None
_get_ermo gets adjacent error code through all file descriptors.
The error code is defined in sys/errno.h.
Error code
GetPadBuf
Gets controller buffers
Structure
void GetPadBuf (
volatile unsigned char **bufl,
volatile unsigned char **buf2
)
Arguments
bufl Pointer to the buffer that stores data from the port 1 controller.
buf2 Pointer to the buffer that stores data from the port 2 controller.
Comments
Communication with the controller is carried out every vertical synchronisation
interruption, and the result stored in controller buffers within the system. The GetPadBuf
function can get the pointers to those buffers.
Two sets of controller buffers are available for the ports, and the following data is stored.
Oxff: Without controller
0x00: With controller
Upper 4bit: Terminal type
Lower 4bit: Received data size (1/2 byte number)
Reception data (largest 32 bytes)
The received data is different according to the controller type shown by ‘terminal type’.
The terminal types supported by this library are as follows.
Please refer to the "Programmer's Guide" for the contents of received data corresponding
to terminal type.
Return value
None
CdPlay
Structure
Arguments
Comments
Plays back CD-DA tracks
int CdPlay (
int mode,
int *tracks,
int offset
)
mode Mode
tracks Array that specifies track to be played. Ends with 0.
offset index of tracks starting the performance
CdPlay plays consecutively in the background multiple tracks specified by the array
tracks. When the last track of the array is played, it repeats or ends the performance,
according to the mode.
Values that can be specified in mode are as follows.
ooo | Stops performance
1 The tracks specified bytracks are played consecutively, and the performance is stopped}
when all the specified tracks have been played.
2 The tracks specified bytracks are played consecutively, and the performance is returned
to the start and repeated when all the specified tracks have been played.
The index of thetracks array for the track currently being played is returned.
Return value
The track currently being played. The index of thetracks array is returned instead of the
track number. The performance is shown as ended if -1 is returned.
Notes
The performance is carried out in track units, Performance and stopping etc. in mid track
is not possible.
CdReadFile
Structure
Arguments
Comments
Return value
int CdReadFile(
char *file,
u_long *addr,
int nbyte
)
file Filename
addr Read memory address
nbyte Read size
CdReadFile reads nbyte of a file on CD-ROM.
The entire file is read if 0 is specified innbyte.
Reads files on CD-ROM
If NULL is specified infile, reading starts from the last location read by CdReadFile
immediately before.
The data number (bytes) read is returned if successful, and 0 is returned in the case of a
reading error.
Notes
The filename must be an absolute path.
Lower case characters are automatically changed to upper case characters.
Reading is carried out in the background, and CdReadSync() is used to determine the end
of reading.
CdReadExec
Structure
Arguments
Comments
Return value
Notes
Loading executable files from CD-ROM
struct EXEC *CdReadExec(
char “file
)
file Executable filename
Executable files specified by file are loaded by CdReadExec from CD-ROM to the
appropriate address in the main memory.
Reading is carried out in the background, and CdReadSync() is used to determine the end
of reading.
The loaded file is executed as a child process by using Exec().
EXEC structure that holds executable files that have been read.
The load address of the executable file should not overlap the area used by the parent
process
CdReadSyne
Waits for termination of CdRead
Structure
int CdReadSync (
int mode,
u_char *result
)
Arguments
mode 0: Waits for termination of read
1: Current condition is checked and immediately returned
result Status of most recently terminated command
Comments.
CdReadSynce waits for reading by CdReadFile() and CdReadExec() to terminate.
Return value
The following values are returned.
Return value Content
Standard integer Remaining sector number
Termination
Read error
CdSearchFile
Structure
Arguments
Comments
Return value
Notes
Gets location and size from filename on CD-ROM
CdIFILE *CdSearchFile (
CdlFILE “fp,
char *name
)
fp CD-ROM file structure pointer
name Filename
CdSearchFile recognises the absolute location (minute, second, sector) and size from the
filename on CD-ROM.
The result is stored in fp.
The pointer of the CD-ROM file structure obtained is returned.
0 is returned if the file is not found, and -1 is returned if the search fails.
The filename must be an absolute path.
File location information in the same directory as files specified byfp are cached in
memory. For this reason, if CdSearchFile() is carried out continuously in files within the
same directory, access becomes faster from the second time.
Cases where the return value is -1 show that the directory read has failed for some reason.
Get VideoM ode()
Obtains the present video signalling system
Structure
long GetVideoMode (void)
Arguments
None
Comments
Returns the present video signaling system declared in SetVideoMode().
Return value
Return value contents is the video signaling system mode
MODE NTSC: NTSC system video signaling system
MODE PAL: PAL system video signaling system
Notes
When SetVideoMode () is not called, no matter what the machine, it will return
MODE NTSC.
See Also
SetVideoMode()
Set VideoMode()
Declares current video signalling system
Structure
long SetVideoMode (
long mode
)
Arguments
mode Video signaling system mode
Comments
Declares the video signaling system indicated bymode to the libraries.
Related libraries will be able to conform to the actions of the declared video signaling
system environment.
Return value
Previously-set video signaling system mode
Mode Contents
MODE NTSC: NTSC system video signaling sytem
MODE PAL: PAL system video signaling system
Notes
Gets called in advance of all library functions.
See Also
GetVideoMode()
TestCard
Structure
Arguments
Comments
Return value
Memory card test
long TestCard (
long chan
)
chan Slot numbers
0: Slot 1
1: Slot 2
TestCard tests the memory card set in the slot specified bychan and returns the result.
Card initialisation is carried out on the memory card control screen of the PlayStation.
One to four vertical synchronisation interruptions at the end of the operation are necessary
(17m to 68m seconds).
0: No card
1: Card present
New card detected
Communication or card abnormality detected
Sane ed
Non-initialised card detected
Index
All structures, functions and external variables explained in this Library Reference are listed in alphabetical
order together with the relavent page number.
COS sistas ele tats te 271 GetChitesnsanaiaatetes 58
COSD 320) ene na 278 GetPadBuf...............:cce 315
Cu a e R 292
BCtSa hei, Sere 247
ADS EA TOTA eee DISPENV GSCELL. oreren 39
ACOS.. soeeeennneeennneeeeans DRAWENV GsSGlearOtr deai otek 132
ApplyMattix.........cceee DrawSync GsCOORDINATE2........... 23
ApplyMatrixLv........06066.79 esses GsDefDispBuff............... 103
GSDOBIJ2.....cceeccceceeeteees 20
GsDrawOt.......eeceeseeeees 133
GSF_LIGHT......escessscsesseees 28
GsFOGPARAM.............65 29
GsGetActiveBuff............. 107
GSGEtLSS TNE N 125
GsGetLw...cccccccccessseceees 124
GsGetLws.......cccceceesseeees 127
GsGetTimInfo................. 113
GsGetWorkBase.............. 137
GSGLIN Bit sidosciocsseiouasaet 43
GSIMAGE........cccccessecesseees 30
GsIncFrame.............::0006 152
GsInit3D.........ccceceeseeeeeeee 102
GsInitCoordinate2............ 123
GsInitFixBg16...........00 142
GsInitGraph....... ee 100
GSIN En senenin eh 41
TEET oma cern cate FntOpen GsLinkObject4................115
CdIPILE iste sarie tae Fates. ccc cuckoo GsMAP.......... seeteeeensensssess 38
CdILOC wo... eee eeeeeeeeeeee font at GsMapModelingData...... 114
CdPlay.......eeeee Fes con NN, 213 ERO EEEE ATE 17
CdReadExec......... eek peep ee pets 283 GSOT_TAG.....eeeeeeeeeee 19
CdReadFile..........cccccccc00 BLD (St terremnneeuaneounnees GSRVIEW2........cccccccceeeeee 26
CdSearchFile........ GsScaleScreen..............06 128
Ceil. LC GsSetAmbient.….............. 122
ClearImage........... GsSetClip...seeeeeeeeeee 112
A EEES TEE ETA E E E E ITAA, 245 GsSetClip2D nnes 150
CompMatix..........cccceee getchat .....eecceccsseesseseees 246 GsSetDrawBuffClip......... 111
GsSetDrawBuffOffset.....108
GsSetFlatLight................ 119
GsSetFogParam............... 121
GsSetLightMatrix............ 131
GsSetLightMode............. 120
GsSetLsMatrix.....
GsSetOffset..........
GsSetOrign..........
GsSetProjection.
GsSetRefView?2............. 116
GsSetView2
GsSetWorkBase..............
GsSortBoxFill...............
GsSortClear..........
GsSortFastSprite.............
GsSortFixBg16.......0..0.. 144
GsSortGLine........ 147
GsSortLine........... 146
GsSortObject4. 134
GsSortOt.......ecceeeseeeeeeee 149
GsSortSprite...........cee 139
GSSPRITE............cccceeeeeees 32
GsSwapDispBuff............ 105
GSVIEW2 uo. ccceceessseeeeees 25
gteMIMefunc.......... 98
KanjiFntClose....... 69
KanjiFntFlush....... 71
KanjiFntOpen........0.... 67
KanjiFntPrint
Krom2Tim.................0066
LoadImage............eeeeeeee
LoadTest.........ccccceeeeeeeeees
MALLOC oooi
MATRIX... eee
MeMCHTY............ cece
MEMCMP...........eeeeeeeeeeeeees
MEMCD)......0:-ceeeeceeeeeeeeees
MEMMOVE..........0:ccceceeeeees
FANG EEA 221
TEAC a se 301
TEAM OCS ave ET 212
RE COT i526 tt SA ess 8
rename 2. att 307
ResetGraph...........eeeeeeee 47
ResetRCOIt nasaia 293
RotMatix........ceee 80
RotMatrixX...........e 82
RotMatrixy ...........eee 84
RotMatrixZ.........cccceeeeeees 86
ScaleMatrix........cceeeeees 89
ScaleMatrixL............cc00 91
SetDispMask..............0008 48
SOUP... eeesceeeeereeeeeenees 253
SetVideoMode().............. 326
SII se tareio n e 270
SIND Sten ae ces 277
SndVolume.............::::c06 156
Sprintl ericson 252
SPUN? nean 285
SOEN ATENa Ea 280
STAN ne ENa 220
SsGetMute...... eee 174
SsGetM Vol... eee 172
SsGetSerialAttr..... 180
SsGetSerialVol.............. 182
SSIS EOS hinti 177
SsPlayBack........ eee 175
SsSeqClose........csceeeees 161
SsSeqGetVol........eeee 167
SsSeqOpen..........eceeeeee 160
SsSeqPause.........ecseceeeees 163
SsSeqPlay.........ceeeeeeeeee 162
SsSeqReplay........... 164
SsSeqSetAcceleranda...... 170
SsSeqSetNext.........ceeee 168
SsSeqSetRitardando......... 169
SsSeqSetVol........c eee 166
SsSeqStop........cccesceeeeees 165
SsSetMute....... cece 173
SsSetMVol.........ceceeeeee 171
SsSetSerialAttr................ 178
SsSetSerialVol................ 181
SsSetTempo
SsUtAl KeyOff............... 199
SsUtChangePitch............ 187
SsUtGetReverbType........ 195
SsUtGetVVol 190
SsUtKeyOff.........
SsUtKeyOn.......... eee
SsUtPitchBend................
SsUtReverbOff....
SsUtReverbOn................
SsUtSetReverbDelay....... 198
SsUtSetReverbDepth....... 196
SsUtSetReverbFeedback. 197
SsUtSetReverbType........ 193
SsUtSetVVOL..... eee
SsVabClose..........
SsVabTransfer......
StartRCnt....... eee
StoreImage..............05
strcat
Re ni OTA
SUCINP oni E ese cee 224
SUCDY napa ann a 225
S10 Cs) 0) | ee 226
ina E a EPEE 227
SENCA oo... eeeeeeeeeeeeeeeeeee 228
StMCMP +5 eee 229
SUITICPY.......eeeeseeeeeeeeeeeeeenee 230
Strpbrle:, ashe. hatte daitienes 231
SUITCHIY. 0... eeeeeeeeeeneeeeeeee 232
SUSPO n nna n aI 233
SES naa e 234
SO d eneore naaa 259
SUrtOk OE 235
SOl na 236
strtoul.....seeeeeeeseeeeseees 238
TestGard 3. Ea aeaa 327
{OASCIT La ya a E 242
tOlOWET .oniinnisssooeenessssseeeeee 243
L20110] oE EEATT 244
TransMatrix...............c008 88
TransposeMatrix................ 93
VECTOR assistants 13
VSN uen 60
VSyncCallback........... 61
Library Reference
Software Development Tool
This product is sold on a membership agreement basis to Members of Net
Yaroze, which is operated by Sony Computer Entertainment Inc.
The ms symbol, PlayStation' and 'NefYaroze' are trademarks of Sony
Computer Entertainment Inc.
Company and product names recorded in/on this product are generally
trademarks of each company. Note that in/on this product the symbols '® 'and 'TM' are not used explicitly.
Published February 1997
©1997 Sony Computer Entertainment Inc. All Rights Reserved.
Written and produced by :
Sony Computer Entertainment Inc.
Akasaka Oji Building
8-1-22 Akasaka, Minato-ku, Tokyo, Japan 107
Enquiries to: Network Business Project
E-mail:ny-info@scei.co.jp
TEL:+81 (0) 3-3475-1711
Sony Computer Entertainment Europe
Waverley House
7-12 Noel Street
London W1V 4HH, England
Inquiries to: TheYaroze Team
E-mail: yaroze-info@scee.sony.co.uk
TEL:+44 (0) 171 447 1616 / +44 (0) 7000 YAROZE
Sony Computer Entertainment America
919 E. Hillsdale Blvd., 2nd Floor
Foster City, CA 94404, USA
Inquiries to: TheYaroze Team
E-mail: yaroze@interactive.sony.com
TEL:+1-415-655-3600
Live Music
Archive
Librivox
Free Audio
Metropolitan Museum
Cleveland
Museum of Art
Internet
Arcade
Console Living Room
Open Library
American
Libraries
TV News
Understanding
9/11